{"openapi":"3.0.3","info":{"title":"PVE Platform API","description":"Multi-tenant platform for managing spaces, resources, users, and groups.\n\n**📚 Documentation Resources:**\n- [Interactive Schema Browser](/api/v1/public/schemas) - Browse all API schemas and data structures\n- [OpenAPI JSON Specification](/api/docs/json) - Raw OpenAPI definition\n- [Taxonomy Guide](https://github.com/pascalgroner/PveAppServices/blob/main/docs/TAXONOMY-API-REFERENCE.md) - Tags & Categories\n- [Application Integration Guide](https://github.com/pascalgroner/PveAppServices/blob/main/docs/APPLICATION-IMPLEMENTATION-GUIDE.md) - How to integrate PVE services\n- [Error Response Standard](https://github.com/pascalgroner/PveAppServices/blob/main/docs/ERROR-RESPONSE-STANDARD.md) - Standardized error formats\n- [Permissions & Roles](https://github.com/pascalgroner/PveAppServices/blob/main/docs/ROLE-HIERARCHY-STANDARD.md) - Authorization model\n- [Enum Values](https://github.com/pascalgroner/PveAppServices/blob/main/docs/SYSTEM-ENUM-INVENTORY.md) - All system enums\n- [Complete Documentation](https://github.com/pascalgroner/PveAppServices/tree/main/docs) - Full docs on GitHub","version":"1.4.1150","contact":{"name":"PVE Platform Team","url":"https://github.com/pascalgroner/PveAppServices"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token obtained from /api/v1/public/auth/login"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for public reference endpoints. Alternatively, use bearerAuth JWT."}},"schemas":{}},"paths":{"/mcp/setup":{"get":{"summary":"MCP server setup guide","tags":["MCP"],"description":"Interactive setup guide for connecting Cursor, VS Code, Windsurf, Claude Desktop, and other MCP clients to this server.","responses":{"200":{"description":"Default Response"}}}},"/mcp/info":{"get":{"summary":"MCP server information","tags":["MCP"],"description":"Returns metadata about the PVE Platform MCP server including available tool categories, built-in prompt templates, and protocol details.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"protocol":{"type":"string"},"specVersion":{"type":"string"},"endpoint":{"type":"string"},"transport":{"type":"string"},"serverName":{"type":"string"},"instructionsSummary":{"type":"string"},"triage":{"type":"object","properties":{"description":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"patterns":{"type":"array","items":{"type":"object","properties":{"intent":{"type":"string"},"firstTools":{"type":"array","items":{"type":"string"}},"thenTools":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}}}}},"prompts":{"type":"object","properties":{"public":{"type":"object","properties":{"description":{"type":"string"},"prompts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}}}},"tools":{"type":"object","properties":{"public":{"type":"object","properties":{"description":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}}}},"authenticated":{"type":"object","properties":{"description":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}},"/api/v1/system/health":{"get":{"summary":"Get system health","tags":["System"],"description":"Multi-level health check (level=basic|ready|full)","parameters":[{"schema":{"type":"string","enum":["basic","ready","full"],"default":"basic"},"in":"query","name":"level","required":false,"description":"Health check detail level"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","healthy"],"description":"Overall system health status"},"version":{"type":"string","description":"API version (e.g., 1.1.123)"},"timestamp":{"type":"string","description":"Health check timestamp (ISO 8601)"},"degradedServices":{"type":"array","items":{"type":"string"},"description":"List of degraded service names (level=basic)"},"ready":{"type":"boolean","description":"System ready status (level=ready, level=full)"},"environment":{"type":"string","description":"Deployment environment (level=ready, level=full)"},"services":{"type":"object","description":"Detailed health status of all services (level=full)","additionalProperties":true},"externalApis":{"type":"object","description":"External API connector health summary (level=full)","properties":{"total":{"type":"integer"},"active":{"type":"integer"},"statusBreakdown":{"type":"object","additionalProperties":{"type":"integer"}}}},"supabaseUrl":{"type":"string","description":"Supabase instance URL used by this backend (origin)"},"centrifugo":{"type":"object","description":"Centrifugo runtime status and version details","properties":{"enabled":{"type":"boolean"},"status":{"type":"string","enum":["ok","degraded","disabled"]},"ready":{"type":"boolean"},"checkedAt":{"type":"string"},"version":{"type":"string"},"message":{"type":"string"},"metrics":{"type":"object","properties":{"nodes":{"type":"integer"},"channels":{"type":"integer"},"clients":{"type":"integer"},"users":{"type":"integer"},"uptimeSeconds":{"type":"integer"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/info":{"get":{"summary":"Get system information","tags":["System"],"description":"Complete system information with all service details","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded"],"description":"Overall system health status"},"version":{"type":"object","properties":{"version":{"type":"string","description":"Full version string (e.g., 1.1.123)"},"major":{"type":"number","description":"Major version number"},"minor":{"type":"number","description":"Minor version number"},"build":{"type":"number","description":"Build number (auto-incremented)"},"buildDate":{"type":"string","description":"Build timestamp (ISO 8601)"}}},"timestamp":{"type":"string","description":"System info check timestamp (ISO 8601)"},"environment":{"type":"string","description":"Deployment environment (development, staging, production)"},"uptime":{"type":"number","description":"Process uptime in seconds"},"services":{"type":"object","description":"Detailed health status of all services","additionalProperties":{"type":"object","properties":{"status":{"type":"string","description":"Service health status (healthy, degraded, unhealthy)"},"message":{"type":"string","description":"Human-readable status message"},"responseTime":{"type":"number","description":"Service response time in milliseconds"},"timestamp":{"type":"string","description":"Last health check timestamp (ISO 8601)"}}}},"centrifugo":{"type":"object","description":"Centrifugo runtime status and version details","properties":{"enabled":{"type":"boolean"},"status":{"type":"string","enum":["ok","degraded","disabled"]},"ready":{"type":"boolean"},"checkedAt":{"type":"string"},"version":{"type":"string"},"message":{"type":"string"},"metrics":{"type":"object","properties":{"nodes":{"type":"integer"},"channels":{"type":"integer"},"clients":{"type":"integer"},"users":{"type":"integer"},"uptimeSeconds":{"type":"integer"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/dispatcher/run":{"post":{"summary":"Run dispatcher jobs","tags":["System"],"description":"Execute scheduled jobs (called by pg_cron)","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-dispatcher-secret","required":false,"description":"Dispatcher API key (preferred)"},{"schema":{"type":"string"},"in":"header","name":"x-cron-secret","required":false,"description":"Cron API key (alternative)"},{"schema":{"type":"string"},"in":"header","name":"authorization","required":false,"description":"Bearer <DISPATCHER_SECRET> (alternative)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"run_id":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"duration_ms":{"type":"number"},"jobs_executed":{"type":"number"},"jobs_failed":{"type":"number"},"jobs_skipped":{"type":"number"},"health_status":{"type":"object","properties":{"overall":{"type":"string","enum":["healthy","degraded"]},"services":{"type":"array","items":{"type":"object","properties":{"service_name":{"type":"string"},"status":{"type":"string"},"message":{"type":"string"}}}}}},"alerts_sent":{"type":"number"}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/v1/system/dispatcher/health":{"get":{"summary":"Get dispatcher health","tags":["System"],"description":"Get service health status","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"overall":{"type":"string","enum":["healthy","degraded"]},"timestamp":{"type":"string","format":"date-time"},"services":{"type":"array","items":{"type":"object","properties":{"service_name":{"type":"string"},"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}}}}},"/api/v1/system/dispatcher/status":{"get":{"summary":"Get dispatcher status","tags":["System"],"description":"Get dispatcher status and recent runs","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-dispatcher-secret","required":false,"description":"Dispatcher API key (preferred)"},{"schema":{"type":"string"},"in":"header","name":"x-cron-secret","required":false,"description":"Cron API key (alternative)"},{"schema":{"type":"string"},"in":"header","name":"authorization","required":false,"description":"Bearer <DISPATCHER_SECRET> (alternative)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["serverless","supabase-scheduler"]},"last_run":{"type":"object","nullable":true,"properties":{"run_id":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"duration_ms":{"type":"number"},"jobs_executed":{"type":"number"},"jobs_failed":{"type":"number"},"health_status":{"type":"object"}}},"recent_runs":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"duration_ms":{"type":"number"},"jobs_executed":{"type":"number"},"jobs_failed":{"type":"number"}}}},"recent_alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"severity":{"type":"string"},"title":{"type":"string"},"message":{"type":"string"},"acknowledged":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/v1/system/dispatcher/alerts/{id}/acknowledge":{"post":{"summary":"Acknowledge dispatcher alert","tags":["System"],"description":"Acknowledge a system alert","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"header","name":"authorization","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/v1/public/auth/login":{"post":{"tags":["Auth"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"rememberMe":{"type":"boolean"},"tenantId":{"type":"string","format":"uuid","description":"Optional tenant ID for multi-tenant login. If not provided and user has multiple tenants, returns tenant list."}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"anyOf":[{"type":"string"},{"type":"null"}]},"groups":{"type":"array","items":{"type":"string"}},"groupDetails":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"required":["id","name","permissions"],"additionalProperties":false}},{"type":"null"}]},"permissions":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"isSystemAdmin":{"type":"boolean"},"isTenantAdmin":{"type":"boolean"}},"required":["id","email","displayName","fullName","tenantId","groups","isSystemAdmin","isTenantAdmin"],"additionalProperties":false},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresIn":{"type":"number"}},"required":["user","accessToken","refreshToken","expiresIn"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/register":{"post":{"tags":["Auth"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password","tenantName","tenantDomain"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"tenantName":{"type":"string","minLength":2,"maxLength":255},"tenantDomain":{"type":"string","pattern":"^[a-z0-9-]+$","minLength":2,"maxLength":63},"displayName":{"type":"string","maxLength":255},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"tenantId":{"type":"string","format":"uuid"}},"required":["id","email","tenantId"],"additionalProperties":false},"tenant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string"}},"required":["id","name","domain"],"additionalProperties":false},"message":{"type":"string"}},"required":["user","tenant","message"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/refresh":{"post":{"tags":["Auth"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresIn":{"type":"number"}},"required":["accessToken","refreshToken","expiresIn"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/providers":{"get":{"summary":"Get enabled OAuth providers","tags":["Auth"],"description":"Returns a list of OAuth providers that are enabled for authentication, along with tenant-specific settings","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false,"description":"Optional tenant ID for tenant-specific settings"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["google","microsoft","apple","facebook","github"],"description":"Provider identifier"},"name":{"type":"string","description":"Display name for the provider"},"enabled":{"type":"boolean","description":"Whether this provider is enabled"},"icon":{"type":"string","description":"Icon name or URL for the provider"},"capabilities":{"type":"object","properties":{"server_callback":{"type":"boolean","description":"Whether the provider supports server-side callback completion in the platform auth broker"},"client_callback":{"type":"boolean","description":"Whether the provider supports the Track 2 client callback broker flow"},"native_mobile":{"type":"boolean","description":"Whether the provider is recommended for native mobile SDK flows"}},"required":["server_callback","client_callback","native_mobile"],"additionalProperties":false}},"required":["id","name","enabled","capabilities"],"additionalProperties":false},"description":"List of available OAuth providers"},"emailEnabled":{"type":"boolean","description":"Whether email/password login is enabled"},"tenantConfig":{"type":"object","properties":{"requireInvitation":{"type":"boolean","description":"Whether users must have an invitation to register"},"allowSelfRegistration":{"type":"boolean","description":"Whether users can self-register without invitation"},"passwordAuthEnabled":{"type":"boolean","description":"Whether email/password authentication is enabled"},"mfaRequired":{"type":"boolean","description":"Whether MFA is required for all users"}},"required":["requireInvitation","allowSelfRegistration","passwordAuthEnabled","mfaRequired"],"additionalProperties":false,"description":"Tenant-specific authentication configuration"}},"required":["data","emailEnabled"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/oauth/initiate":{"post":{"summary":"Initiate OAuth client callback flow","tags":["Auth"],"description":"Starts Track 2 OAuth authentication for client-owned callback routes","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["google","microsoft","apple","facebook","github"],"description":"OAuth provider to authenticate with"},"redirectUrl":{"type":"string","minLength":1,"description":"Client-owned callback URI (https://, chrome-extension://, or app:// depending on configuration)"},"tenantId":{"type":"string","format":"uuid","description":"Optional tenant ID for multi-tenant login"},"clientType":{"type":"string","enum":["web","extension","desktop","mobile"],"description":"Client type initiating the OAuth broker flow"}},"required":["provider","redirectUrl","clientType"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"oauthUrl":{"type":"string","description":"OAuth provider authorization URL"},"provider":{"type":"string","enum":["google","microsoft","apple","facebook","github"]},"clientType":{"type":"string","enum":["web","extension","desktop","mobile"]},"redirectMode":{"type":"string","enum":["client_callback"]},"stateId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"}},"required":["oauthUrl","provider","clientType","redirectMode","stateId","expiresAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/oauth/exchange":{"post":{"summary":"Exchange OAuth client callback code","tags":["Auth"],"description":"Completes Track 2 OAuth authentication from a client-owned callback route without exposing direct Supabase auth setup to the frontend","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"Authorization code returned to the client-owned callback route"},"pveState":{"type":"string","format":"uuid","description":"PVE-issued OAuth state ID returned in the client-owned callback route"}},"required":["code","pveState"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["authenticated","registration_required"]},"provider":{"type":"string","enum":["google","microsoft","apple","facebook","github"]},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"requiresPostAuthFlow":{"type":"boolean"},"user":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"groupDetails":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"required":["id","name","permissions"],"additionalProperties":false}},"permissions":{"type":"array","items":{"type":"string"}},"isSystemAdmin":{"type":"boolean"},"isTenantAdmin":{"type":"boolean"}},"required":["id","email","displayName","fullName","tenantId","tenantName","groups","groupDetails","permissions","isSystemAdmin","isTenantAdmin"],"additionalProperties":false},{"type":"null"}]},"registration":{"anyOf":[{"type":"object","properties":{"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"},"tenantId":{"type":"string","format":"uuid"}},"required":["email"],"additionalProperties":false},{"type":"null"}]}},"required":["status","provider","accessToken","refreshToken","requiresPostAuthFlow"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/oauth/register":{"post":{"summary":"Complete OAuth registration","tags":["Auth"],"description":"Creates a platform account for an OAuth-authenticated user","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"displayName":{"type":"string"},"registrationMode":{"type":"string","enum":["create_tenant","join_tenant","system_tenant"]},"tenantName":{"type":"string"},"tenantDomain":{"type":"string"},"inviteCode":{"type":"string"},"locale":{"type":"string"}},"required":["accessToken","refreshToken","registrationMode"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"displayName":{"type":"string"},"fullName":{"type":"string"},"tenantId":{"type":"string"},"tenantName":{"type":"string"}},"required":["id","email","displayName","fullName","tenantId","tenantName"],"additionalProperties":false},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"requiresPostAuthFlow":{"type":"boolean"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/auth/merge-accounts":{"post":{"summary":"Merge secondary auth account","tags":["Auth"],"description":"Merges a verified secondary auth account into the current authenticated user","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"secondaryAccessToken":{"type":"string","minLength":1,"description":"Access token for the secondary account to merge into the current authenticated account"},"mergeMode":{"type":"string","enum":["move_all","safe_only"],"description":"Requested merge mode"},"dryRun":{"type":"boolean","description":"Whether to calculate the merge plan without applying changes"}},"required":["secondaryAccessToken"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"primaryUserId":{"type":"string","format":"uuid"},"secondaryUserId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["planned","completed","failed","dry_run"]},"reassignedEntities":{"type":"object","additionalProperties":{"type":"integer"}},"warnings":{"type":"array","items":{"type":"string"}},"deletedSecondaryAccount":{"type":"boolean"}},"required":["primaryUserId","secondaryUserId","status","reassignedEntities","warnings","deletedSecondaryAccount"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/register-user":{"post":{"summary":"Register new user","tags":["Auth"],"description":"Self-service user registration in an existing tenant context. Provide tenantId, X-Tenant-ID, or use a mapped tenant domain.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"displayName":{"type":"string","maxLength":255},"tenantId":{"type":"string","format":"uuid","description":"Tenant context for self-registration. Required unless the tenant is resolved from X-Tenant-ID or a mapped custom domain."}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"userId":{"type":"string","format":"uuid"},"requiresVerification":{"type":"boolean","description":"Whether the created account must complete email verification before it can be used."},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"},"tenantId":{"type":"string","format":"uuid"}},"required":["id","email","displayName","fullName","tenantId"],"additionalProperties":false},"tenant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"}},"required":["id","name","slug","domain"],"additionalProperties":false}},"required":["message","userId","requiresVerification","user","tenant"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/forgot-password":{"post":{"summary":"Request password reset","tags":["Auth"],"description":"Queue a password reset message for the user. Always returns success for security.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/validate-reset-token":{"get":{"summary":"Validate reset token","tags":["Auth"],"description":"Check if a password reset token is valid and not expired","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"email":{"type":"string","format":"email"}},"required":["valid"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/reset-password":{"post":{"summary":"Reset password","tags":["Auth"],"description":"Set new password using a valid reset token. Token is single-use.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["token","password"],"properties":{"token":{"type":"string","minLength":1},"password":{"type":"string","minLength":8}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/auth/user-tenants":{"get":{"summary":"Get user tenants by email","tags":["Auth"],"description":"Returns list of tenants the user has access to. For security, always returns an empty list for non-existent users.","parameters":[{"schema":{"type":"string","format":"email"},"in":"query","name":"email","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"tenants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"]}},"hasMultipleTenants":{"type":"boolean"}},"required":["tenants","hasMultipleTenants"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/invitations/validate":{"post":{"summary":"Validate invitation code","tags":["Invitations"],"description":"Check if an invitation code is valid and get invitation details","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Invitation code to validate"}},"required":["code"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"invitation":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenant_name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","guest"]},"recipient_email":{"type":"string","nullable":true},"recipient_phone":{"type":"string","nullable":true},"invited_by_name":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time"}},"nullable":true},"error":{"type":"string","nullable":true}},"required":["valid"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/invitations/accept":{"post":{"summary":"Accept invitation","tags":["Invitations"],"description":"Accept an invitation and create a new user account (or link to existing via OAuth)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Invitation code"},"email":{"type":"string","format":"email","description":"Email for new account (must match invitation if email-based)"},"password":{"type":"string","minLength":8,"description":"Password for new account (required for password auth)"},"display_name":{"type":"string","description":"Display name for new account"},"oauth_access_token":{"type":"string","description":"OAuth access token (for social login registration)"},"oauth_refresh_token":{"type":"string","description":"OAuth refresh token (for social login registration)"}},"required":["code"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"},"tenantId":{"type":"string","format":"uuid"},"tenant_name":{"type":"string"},"role":{"type":"string"}},"required":["id","email","displayName","fullName","tenantId","tenant_name","role"]},"access_token":{"type":"string"},"refresh_token":{"type":"string"},"requires_post_auth_flow":{"type":"boolean"}},"required":["success","message","user","access_token","refresh_token"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/qr/{uuid}":{"get":{"summary":"Public QR code embed","tags":["Public"],"description":"Get QR code image for embedding. Access depends on QR code access_level setting.","parameters":[{"schema":{"type":"string","enum":["png","svg"],"default":"png"},"in":"query","name":"format","required":false,"description":"Output format"},{"schema":{"type":"integer","minimum":64,"maximum":4096},"in":"query","name":"size","required":false,"description":"Override size"},{"schema":{"type":"string"},"in":"query","name":"theme","required":false,"description":"Override theme"},{"schema":{"type":"string"},"in":"query","name":"downloadToken","required":false,"description":"Ephemeral download token"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"QR code image","content":{"application/json":{"schema":{"description":"QR code image","type":"string","format":"binary"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"429":{"description":"429 Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Error code for rate limit errors","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[429]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"429 Too Many Requests - Rate limit exceeded"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/public/countries/":{"get":{"summary":"List all countries with optional filters and prioritization","tags":["Countries (Public)"],"description":"Get all countries with optional search, region filter, localization, and prioritized sorting. Priority countries appear first, followed by alphabetically sorted remaining countries. No tenant isolation - same data for all tenants.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"examples":{"swi":{"value":"swi"},"deutschland":{"value":"deutschland"},"ไทย":{"value":"ไทย"}},"in":"query","name":"search","required":false,"description":"Search term for country name (ASCII or localized)"},{"schema":{"type":"string"},"examples":{"Europe":{"value":"Europe"},"Asia":{"value":"Asia"},"Americas":{"value":"Americas"}},"in":"query","name":"region","required":false,"description":"Filter by region (exact match)"},{"schema":{"type":"string","pattern":"^[a-z]{2}$"},"examples":{"en":{"value":"en"},"de":{"value":"de"},"fr":{"value":"fr"},"th":{"value":"th"}},"in":"query","name":"language","required":false,"description":"Preferred language for localized names (ISO 639-1)"},{"schema":{"type":"string","pattern":"^[A-Z]{2,3}(,[A-Z]{2,3})*$"},"examples":{"CH,DE":{"value":"CH,DE"},"US,CA,MX":{"value":"US,CA,MX"},"TH":{"value":"TH"}},"in":"query","name":"priorityCountries","required":false,"description":"Comma-separated list of country codes (alpha-2 or alpha-3) to prioritize (appear first in results). Defaults to CH,DE,FR,IT."},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false,"description":"Number of countries per page"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Number of countries to skip"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z]{2,3}$","description":"Universal country code: ISO 3166-1 alpha-2 when available, else alpha-3. Primary key.","example":"CH"},"iso_code":{"type":"string","pattern":"^[A-Z]{2}$","nullable":true,"description":"ISO 3166-1 alpha-2 country code (2 uppercase letters). Null for entities without an official alpha-2 code.","example":"CH"},"numeric_code":{"type":"string","pattern":"^[0-9]{3}$","nullable":true,"description":"ISO 3166-1 numeric country code (3 digits). Null when unavailable.","example":"756"},"cca3":{"type":"string","pattern":"^[A-Z]{3}$","nullable":true,"description":"ISO 3166-1 alpha-3 country code (3 uppercase letters)","example":"CHE"},"emoji":{"type":"string","nullable":true,"description":"Flag emoji for the country","example":"🇨🇭"},"name_ascii":{"type":"string","description":"International country name in English (ASCII-safe)","example":"Switzerland"},"name_local":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized country names per language code","example":{"de":"Schweiz","fr":"Suisse","it":"Svizzera","rm":"Svizra"}},"flag_url":{"type":"string","format":"uri","description":"PNG flag image URL (self-hosted, served by the backend at /api/v1/public/flags/:code/png)","example":"/api/v1/public/flags/ch/png"},"flag_svg":{"type":"string","format":"uri","nullable":true,"description":"SVG flag image URL (self-hosted, served by the backend at /api/v1/public/flags/:code/svg)","example":"/api/v1/public/flags/ch/svg"},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{3}$"},"nullable":true,"description":"ISO 4217 currency codes used in this country","example":["CHF"]},"phone_code":{"type":"string","pattern":"^\\+[0-9]{1,4}$","nullable":true,"description":"International Direct Dialing code","example":"+41"},"metadata":{"type":"object","properties":{"region":{"type":"string","example":"Europe"},"calling_code":{"type":"string","example":"+41"},"currency_code":{"type":"string","example":"CHF"},"capital":{"type":"string","example":"Bern"}},"additionalProperties":true,"description":"Additional metadata (region, calling code, currency, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when country was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when country was last updated"},"name":{"type":"string","description":"Localized name based on language query parameter (computed field)","example":"Schweiz"}},"required":["code","name_ascii","name_local","flag_url","metadata","created_at","updated_at","name"],"additionalProperties":false}},"total":{"type":"integer","minimum":0,"description":"Total number of countries matching filters"},"limit":{"type":"integer","minimum":1,"maximum":500,"description":"Number of countries per page"},"offset":{"type":"integer","minimum":0,"description":"Number of countries skipped"}},"required":["countries","total","limit","offset"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/countries/regions":{"get":{"summary":"Get unique regions list","tags":["Countries (Public)"],"description":"Get list of unique regions from country metadata (e.g., Europe, Asia, Americas).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"regions":{"type":"array","items":{"type":"string"},"description":"List of unique regions from country metadata","example":["Africa","Americas","Asia","Europe","Oceania"]}},"required":["regions"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/countries/{isoCode}":{"get":{"summary":"Get country by ISO code","tags":["Countries (Public)"],"description":"Get single country by universal code: ISO 3166-1 alpha-2 when available, else alpha-3 (e.g., CH, DE, ABK). Returns localized name based on language parameter or Accept-Language header.","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}$"},"examples":{"en":{"value":"en"},"de":{"value":"de"},"fr":{"value":"fr"},"th":{"value":"th"}},"in":"query","name":"language","required":false,"description":"Preferred language for localized name (ISO 639-1)"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2,3}$"},"examples":{"CH":{"value":"CH"},"DE":{"value":"DE"},"ABK":{"value":"ABK"}},"in":"path","name":"isoCode","required":true,"description":"Universal country code: ISO 3166-1 alpha-2 or alpha-3 (2–3 letters)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z]{2,3}$","description":"Universal country code: ISO 3166-1 alpha-2 when available, else alpha-3. Primary key.","example":"CH"},"iso_code":{"type":"string","pattern":"^[A-Z]{2}$","nullable":true,"description":"ISO 3166-1 alpha-2 country code (2 uppercase letters). Null for entities without an official alpha-2 code.","example":"CH"},"numeric_code":{"type":"string","pattern":"^[0-9]{3}$","nullable":true,"description":"ISO 3166-1 numeric country code (3 digits). Null when unavailable.","example":"756"},"cca3":{"type":"string","pattern":"^[A-Z]{3}$","nullable":true,"description":"ISO 3166-1 alpha-3 country code (3 uppercase letters)","example":"CHE"},"emoji":{"type":"string","nullable":true,"description":"Flag emoji for the country","example":"🇨🇭"},"name_ascii":{"type":"string","description":"International country name in English (ASCII-safe)","example":"Switzerland"},"name_local":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized country names per language code","example":{"de":"Schweiz","fr":"Suisse","it":"Svizzera","rm":"Svizra"}},"flag_url":{"type":"string","format":"uri","description":"PNG flag image URL (self-hosted, served by the backend at /api/v1/public/flags/:code/png)","example":"/api/v1/public/flags/ch/png"},"flag_svg":{"type":"string","format":"uri","nullable":true,"description":"SVG flag image URL (self-hosted, served by the backend at /api/v1/public/flags/:code/svg)","example":"/api/v1/public/flags/ch/svg"},"metadata":{"type":"object","properties":{"region":{"type":"string","example":"Europe"},"calling_code":{"type":"string","example":"+41"},"currency_code":{"type":"string","example":"CHF"},"capital":{"type":"string","example":"Bern"},"languages":{"type":"array","items":{"type":"string"},"example":["de","fr","it","rm","en"]}},"additionalProperties":true,"description":"Additional metadata (region, calling code, currency, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when country was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when country was last updated"},"name":{"type":"string","description":"Localized name based on language query parameter (computed field)","example":"Schweiz"}},"required":["code","name_ascii","name_local","flag_url","metadata","created_at","updated_at","name"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/flags/{iso}/{format}":{"get":{"summary":"Get country flag image","tags":["Flags (Public)"],"description":"Returns a self-hosted PNG or SVG flag image for a universal country code (ISO 3166-1 alpha-2 when available, else alpha-3). Images are populated during reference-data sync. Returns 404 if not yet synced.","parameters":[{"schema":{"type":"string"},"in":"path","name":"iso","required":true,"description":"Universal country code: ISO 3166-1 alpha-2 or alpha-3 (case-insensitive, e.g. CH, de, ABK)"},{"schema":{"type":"string","enum":["png","svg"]},"in":"path","name":"format","required":true,"description":"Image format: png (raster, w320) or svg (scalable vector)"}],"responses":{"200":{"description":"Flag image binary","content":{"application/json":{"schema":{"description":"Flag image binary","type":"string"}}}},"400":{"description":"Invalid ISO code or format","content":{"application/json":{"schema":{"description":"Invalid ISO code or format","type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Flag not found — sync may not have run yet","content":{"application/json":{"schema":{"description":"Flag not found — sync may not have run yet","type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/public/languages/":{"get":{"summary":"List all languages with optional filters and prioritization","tags":["Languages (Public)"],"description":"\n          Get all languages with optional search, prioritization, and country-specific filtering.\n\n          **Prioritization Logic:**\n          - Default priority languages: de, fr, it, es (shown first)\n          - If countryCode provided: adds country-specific languages + en to top\n          - Example: ?countryCode=CH → de,fr,it,rm,en appear first\n\n          **Supported Country Codes:** CH, DE, FR, IT, ES, US, GB, TH, JP, CN, KR\n\n          No tenant isolation - same data for all tenants.\n        ","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"examples":{"Korean":{"value":"Korean"},"ไทย":{"value":"ไทย"},"ko":{"value":"ko"},"tha":{"value":"tha"}},"in":"query","name":"search","required":false,"description":"Search in name_english, name_local, or ISO codes"},{"schema":{"type":"string","pattern":"^[a-z]{2}(,[a-z]{2})*$"},"examples":{"de,fr,it":{"value":"de,fr,it"},"en,es":{"value":"en,es"},"ko,ja,zh":{"value":"ko,ja,zh"}},"in":"query","name":"priorityLanguages","required":false,"description":"Comma-separated list of ISO 639-1 codes to prioritize (show first)"},{"schema":{"type":"string","pattern":"^[A-Z]{2,3}$"},"examples":{"CH":{"value":"CH"},"DE":{"value":"DE"},"TH":{"value":"TH"},"US":{"value":"US"}},"in":"query","name":"countryCode","required":false,"description":"Country code (alpha-2 or alpha-3, adds country-specific languages to priority list)"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false,"description":"Maximum number of results per page"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Number of results to skip (pagination offset)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"object","properties":{"iso_code_1":{"type":"string","pattern":"^[a-z]{2}$","description":"ISO 639-1 two-letter language code (lowercase)","example":"en"},"iso_code_2":{"type":"string","pattern":"^[a-z]{3}$","nullable":true,"description":"ISO 639-2 three-letter language code (lowercase)","example":"eng"},"iso_code_3":{"type":"string","pattern":"^[a-z]{3}$","nullable":true,"description":"ISO 639-3 three-letter language code (lowercase, alternative)","example":"eng"},"name_english":{"type":"string","description":"English name of the language (international standard)","example":"English"},"name_local":{"type":"string","description":"Native name in language's own script (UTF-8)","example":"English"},"country_code":{"type":"string","pattern":"^[A-Z]{2,3}$","nullable":true,"description":"Country code (alpha-2 or alpha-3) for flag display","example":"GB"},"metadata":{"type":"object","properties":{"script":{"type":"string","example":"Latin"},"language_family":{"type":"string","example":"Germanic"},"speakers_millions":{"type":"number","example":1500}},"additionalProperties":true,"description":"Additional metadata (script, language family, speaker count, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when language was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when language was last updated"}},"required":["iso_code_1","name_english","name_local","metadata","created_at","updated_at"],"additionalProperties":false}},"total":{"type":"integer","minimum":0,"description":"Total number of languages matching filters"},"limit":{"type":"integer","minimum":1,"maximum":500,"description":"Maximum number of results per page"},"offset":{"type":"integer","minimum":0,"description":"Number of results skipped (pagination offset)"}},"required":["languages","total","limit","offset"]}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/languages/{code}":{"get":{"summary":"Get language by ISO code","tags":["Languages (Public)"],"description":"\n          Get single language by ISO 639-1, 639-2, or 639-3 code.\n\n          **Supported Code Formats:**\n          - ISO 639-1 (2 chars): en, de, ko, th\n          - ISO 639-2 (3 chars): eng, deu, kor, tha\n          - ISO 639-3 (3 chars): eng, deu, kor, tha\n\n          Returns name_english (e.g., \"Korean\") and name_local (e.g., \"한국어\").\n        ","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2,3}$"},"examples":{"en":{"value":"en"},"de":{"value":"de"},"ko":{"value":"ko"},"th":{"value":"th"},"eng":{"value":"eng"},"kor":{"value":"kor"},"tha":{"value":"tha"}},"in":"path","name":"code","required":true,"description":"ISO 639-1/2/3 language code (2 or 3 lowercase letters)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"iso_code_1":{"type":"string","pattern":"^[a-z]{2}$","description":"ISO 639-1 two-letter language code (lowercase)","example":"en"},"iso_code_2":{"type":"string","pattern":"^[a-z]{3}$","nullable":true,"description":"ISO 639-2 three-letter language code (lowercase)","example":"eng"},"iso_code_3":{"type":"string","pattern":"^[a-z]{3}$","nullable":true,"description":"ISO 639-3 three-letter language code (lowercase, alternative)","example":"eng"},"name_english":{"type":"string","description":"English name of the language (international standard)","example":"English"},"name_local":{"type":"string","description":"Native name in language's own script (UTF-8)","example":"English"},"country_code":{"type":"string","pattern":"^[A-Z]{2,3}$","nullable":true,"description":"Country code (alpha-2 or alpha-3) for flag display","example":"GB"},"metadata":{"type":"object","properties":{"script":{"type":"string","example":"Latin"},"language_family":{"type":"string","example":"Germanic"},"speakers_millions":{"type":"number","example":1500}},"additionalProperties":true,"description":"Additional metadata (script, language family, speaker count, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when language was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when language was last updated"}},"required":["iso_code_1","name_english","name_local","metadata","created_at","updated_at"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/currencies/":{"get":{"summary":"List currencies","tags":["currencies"],"description":"List all currencies with optional search and pagination","parameters":[{"schema":{"type":"string"},"examples":{"EUR":{"value":"EUR"},"euro":{"value":"euro"},"dollar":{"value":"dollar"}},"in":"query","name":"search","required":false,"description":"Search by currency code or name (case-insensitive)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false,"description":"Number of results to return"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Number of results to skip"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code (3 uppercase letters)","example":"CHF"},"name":{"type":"string","description":"Full currency name in English","example":"Swiss franc"},"symbol":{"type":"string","nullable":true,"description":"Currency symbol (UTF-8)","example":"CHF"},"metadata":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 country codes using this currency","example":["CH","LI"]},"decimal_digits":{"type":"integer","description":"Number of decimal digits","example":2},"numeric_code":{"type":"string","description":"ISO 4217 numeric code","example":"756"}},"additionalProperties":true,"description":"Additional metadata (countries, decimal digits, numeric code, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when currency was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when currency was last updated"}},"required":["code","name","metadata","created_at","updated_at"],"additionalProperties":false},"description":"Array of currencies"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Currency not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Currency not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/currencies/{code}":{"get":{"summary":"Get currency by code","tags":["currencies"],"description":"Get single currency by ISO 4217 code","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{3}$"},"examples":{"CHF":{"value":"CHF"},"EUR":{"value":"EUR"},"USD":{"value":"USD"}},"in":"path","name":"code","required":true,"description":"ISO 4217 currency code (3 uppercase letters)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code (3 uppercase letters)","example":"CHF"},"name":{"type":"string","description":"Full currency name in English","example":"Swiss franc"},"symbol":{"type":"string","nullable":true,"description":"Currency symbol (UTF-8)","example":"CHF"},"metadata":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 country codes using this currency","example":["CH","LI"]},"decimal_digits":{"type":"integer","description":"Number of decimal digits","example":2},"numeric_code":{"type":"string","description":"ISO 4217 numeric code","example":"756"}},"additionalProperties":true,"description":"Additional metadata (countries, decimal digits, numeric code, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when currency was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when currency was last updated"}},"required":["code","name","metadata","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Currency not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Currency not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Currency not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/currencies/country/{country}":{"get":{"summary":"List currencies by country","tags":["currencies"],"description":"Get currencies used by specific country","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2,3}$"},"in":"path","name":"country","required":true,"description":"Country code: ISO 3166-1 alpha-2 or alpha-3"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code (3 uppercase letters)","example":"CHF"},"name":{"type":"string","description":"Full currency name in English","example":"Swiss franc"},"symbol":{"type":"string","nullable":true,"description":"Currency symbol (UTF-8)","example":"CHF"},"metadata":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 country codes using this currency","example":["CH","LI"]},"decimal_digits":{"type":"integer","description":"Number of decimal digits","example":2},"numeric_code":{"type":"string","description":"ISO 4217 numeric code","example":"756"}},"additionalProperties":true,"description":"Additional metadata (countries, decimal digits, numeric code, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when currency was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when currency was last updated"}},"required":["code","name","metadata","created_at","updated_at"],"additionalProperties":false},"description":"Array of currencies"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Currency not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Currency not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Currency not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone-codes/":{"get":{"summary":"List phone codes","tags":["phone-codes"],"description":"List all international phone codes","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"country_code":{"type":"string","pattern":"^[A-Z]{2,3}$","description":"Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 uppercase letters)","example":"CH"},"idd_root":{"type":"string","pattern":"^\\+[0-9]{1,4}$","description":"International Direct Dialing root code","example":"+41"},"idd_suffixes":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Additional dialing suffixes (if applicable)","example":["0"]},"full_code":{"type":"string","description":"Complete phone code (idd_root + first suffix)","example":"+41"},"metadata":{"type":"object","properties":{"country_name":{"type":"string","description":"Country name for display","example":"Switzerland"},"region":{"type":"string","description":"Geographic region","example":"Europe"}},"additionalProperties":true,"description":"Additional metadata (country name, region, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when phone code was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when phone code was last updated"}},"required":["country_code","idd_root","full_code","metadata","created_at","updated_at"],"additionalProperties":false},"description":"Array of phone codes"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Phone code not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone-codes/search":{"get":{"summary":"Search phone codes","tags":["phone-codes"],"description":"Search phone codes by IDD code (reverse lookup)","parameters":[{"schema":{"type":"string","pattern":"^\\+[0-9]{1,4}$"},"examples":{"+41":{"value":"+41"},"+1":{"value":"+1"},"+66":{"value":"+66"}},"in":"query","name":"code","required":false,"description":"Search by phone code (URL-encoded)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"country_code":{"type":"string","pattern":"^[A-Z]{2,3}$","description":"Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 uppercase letters)","example":"CH"},"idd_root":{"type":"string","pattern":"^\\+[0-9]{1,4}$","description":"International Direct Dialing root code","example":"+41"},"idd_suffixes":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Additional dialing suffixes (if applicable)","example":["0"]},"full_code":{"type":"string","description":"Complete phone code (idd_root + first suffix)","example":"+41"},"metadata":{"type":"object","properties":{"country_name":{"type":"string","description":"Country name for display","example":"Switzerland"},"region":{"type":"string","description":"Geographic region","example":"Europe"}},"additionalProperties":true,"description":"Additional metadata (country name, region, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when phone code was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when phone code was last updated"}},"required":["country_code","idd_root","full_code","metadata","created_at","updated_at"],"additionalProperties":false},"description":"Array of phone codes"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Phone code not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Phone code not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Phone code not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone-codes/{country}":{"get":{"summary":"Get phone code by country","tags":["phone-codes"],"description":"Get phone code by country ISO code","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2,3}$"},"examples":{"CH":{"value":"CH"},"DE":{"value":"DE"},"TH":{"value":"TH"}},"in":"path","name":"country","required":true,"description":"Country code: ISO 3166-1 alpha-2 or alpha-3 (2–3 uppercase letters)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"country_code":{"type":"string","pattern":"^[A-Z]{2,3}$","description":"Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 uppercase letters)","example":"CH"},"idd_root":{"type":"string","pattern":"^\\+[0-9]{1,4}$","description":"International Direct Dialing root code","example":"+41"},"idd_suffixes":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Additional dialing suffixes (if applicable)","example":["0"]},"full_code":{"type":"string","description":"Complete phone code (idd_root + first suffix)","example":"+41"},"metadata":{"type":"object","properties":{"country_name":{"type":"string","description":"Country name for display","example":"Switzerland"},"region":{"type":"string","description":"Geographic region","example":"Europe"}},"additionalProperties":true,"description":"Additional metadata (country name, region, etc.)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when phone code was added"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when phone code was last updated"}},"required":["country_code","idd_root","full_code","metadata","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Phone code not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Phone code not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Phone code not found"},"statusCode":{"type":"integer","description":"HTTP status code","example":400},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp (ISO 8601)"},"details":{"type":"object","description":"Additional error context","additionalProperties":true}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/timezones/":{"get":{"summary":"List all IANA timezones with optional filters","tags":["Timezones (Public)"],"description":"\n          Get all IANA timezones with optional search and region filtering.\n          \n          **Performance:** Data is served from RAM cache (no database queries).\n          First request builds the cache, subsequent requests are instant.\n          \n          **Priority Timezones:** Europe/Zurich, Europe/Berlin, Europe/Paris,\n          Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo,\n          Asia/Singapore, Australia/Sydney are shown first.\n          \n          **Sorting:** Priority timezones first, then by region alphabetically,\n          then by city within each region.\n          \n          No tenant isolation - same data for all tenants.\n        ","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"examples":{"Zurich":{"value":"Zurich"},"York":{"value":"York"},"Europe":{"value":"Europe"}},"in":"query","name":"search","required":false,"description":"Search in timezone name, city, or region"},{"schema":{"type":"string"},"examples":{"Europe":{"value":"Europe"},"America":{"value":"America"},"Asia":{"value":"Asia"}},"in":"query","name":"region","required":false,"description":"Filter by region (e.g., Europe, America, Asia)"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false,"description":"Maximum number of results per page"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Number of results to skip (pagination offset)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"timezones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"IANA timezone name","example":"Europe/Zurich"},"offset":{"type":"string","description":"Current UTC offset (varies with DST)","example":"GMT+1"},"offsetMinutes":{"type":"integer","description":"Offset in minutes for sorting"},"region":{"type":"string","description":"Geographic region","example":"Europe"},"city":{"type":"string","description":"City or location name","example":"Zurich"},"abbreviation":{"type":"string","description":"Timezone abbreviation","example":"CET"}},"required":["name","offset","offsetMinutes","region","city","abbreviation"],"additionalProperties":false}},"total":{"type":"integer","minimum":0,"description":"Total number of timezones matching filters"},"limit":{"type":"integer","minimum":1,"maximum":500,"description":"Maximum number of results per page"},"offset":{"type":"integer","minimum":0,"description":"Number of results skipped (pagination offset)"}},"required":["timezones","total","limit","offset"]}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/timezones/regions":{"get":{"summary":"Get list of available timezone regions","tags":["Timezones (Public)"],"description":"\n          Get all available timezone regions (e.g., Africa, America, Asia, Europe).\n          \n          **Performance:** Data is served from RAM cache.\n          \n          Useful for building region dropdown filters.\n        ","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"},"description":"List of available timezone regions","example":["Africa","America","Antarctica","Asia","Atlantic","Australia","Europe","Indian","Pacific"]}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/timezones/{name}":{"get":{"summary":"Get timezone by IANA name","tags":["Timezones (Public)"],"description":"\n          Get single timezone by IANA name.\n          \n          **Performance:** Data is served from RAM cache.\n          \n          **Example names:** Europe/Zurich, America/New_York, Asia/Tokyo\n          \n          Note: Use URL encoding for names with special characters\n          (e.g., America%2FNew_York).\n        ","parameters":[{"schema":{"type":"string"},"examples":{"Europe/Zurich":{"value":"Europe/Zurich"},"America/New_York":{"value":"America/New_York"},"Asia/Tokyo":{"value":"Asia/Tokyo"}},"in":"path","name":"name","required":true,"description":"IANA timezone name (e.g., Europe/Zurich, America/New_York)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string","description":"IANA timezone name","example":"Europe/Zurich"},"offset":{"type":"string","description":"Current UTC offset","example":"GMT+1"},"offsetMinutes":{"type":"integer","description":"Offset in minutes"},"region":{"type":"string","description":"Geographic region","example":"Europe"},"city":{"type":"string","description":"City name","example":"Zurich"},"abbreviation":{"type":"string","description":"Timezone abbreviation","example":"CET"}},"required":["name","offset","offsetMinutes","region","city","abbreviation"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone/validate":{"post":{"summary":"Validate phone number","tags":["Phone Validation (Public)"],"description":"Validate phone number format and return detailed information if valid","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"Phone number (e.g., +41 79 123 45 67)"},"country_code":{"type":"string","pattern":"^[A-Z]{2,3}$","description":"Country code: alpha-2 or alpha-3 (e.g., CH, ABK)"}}}}},"required":true},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the phone number is valid"},"formatted":{"anyOf":[{"type":"object","properties":{"e164":{"type":"string"},"international":{"type":"string"},"national":{"type":"string"},"rfc3966":{"type":"string"}},"required":["e164","international","national","rfc3966"],"additionalProperties":false},{"type":"string"}],"description":"Formatted phone number payload (validate: all formats, format endpoint: requested single format)"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"national_number":{"type":"string","description":"National number without country prefix"},"extension":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone extension if present"},"calling_code":{"type":"string","description":"Country calling code (without + prefix)"},"type":{"anyOf":[{"type":"string","enum":["fixed_line","mobile","fixed_line_or_mobile","toll_free","premium_rate","shared_cost","voip","personal_number","pager","uan","voicemail","unknown"]},{"type":"null"}],"description":"Normalized line type from libphonenumber-js"},"countries":{"type":"array","items":{"type":"string"},"description":"Supported countries (countries endpoint)"},"count":{"type":"number","description":"Total result count for list-style responses"},"country_name":{"type":"string","description":"Full country name (if available)"},"carrier":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mobile carrier name (if available)"},"line_type":{"anyOf":[{"type":"string","enum":["mobile","landline","voip","toll-free","unknown"]},{"type":"null"}],"description":"Type of phone line"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Geographic location (if available)"},"error":{"type":"string","description":"Validation or parsing error message"}},"required":[],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone/format":{"post":{"summary":"Format phone number","tags":["Phone Validation (Public)"],"description":"Format phone number in specified format","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"Phone number (e.g., +41791234567)"},"country_code":{"type":"string","pattern":"^[A-Z]{2,3}$","description":"Country code: alpha-2 or alpha-3 (e.g., CH, ABK)"},"format":{"type":"string","enum":["E.164","INTERNATIONAL","NATIONAL","RFC3966"],"default":"E.164"}}}}},"required":true},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the phone number is valid"},"formatted":{"anyOf":[{"type":"object","properties":{"e164":{"type":"string"},"international":{"type":"string"},"national":{"type":"string"},"rfc3966":{"type":"string"}},"required":["e164","international","national","rfc3966"],"additionalProperties":false},{"type":"string"}],"description":"Formatted phone number payload (validate: all formats, format endpoint: requested single format)"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"national_number":{"type":"string","description":"National number without country prefix"},"extension":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone extension if present"},"calling_code":{"type":"string","description":"Country calling code (without + prefix)"},"type":{"anyOf":[{"type":"string","enum":["fixed_line","mobile","fixed_line_or_mobile","toll_free","premium_rate","shared_cost","voip","personal_number","pager","uan","voicemail","unknown"]},{"type":"null"}],"description":"Normalized line type from libphonenumber-js"},"countries":{"type":"array","items":{"type":"string"},"description":"Supported countries (countries endpoint)"},"count":{"type":"number","description":"Total result count for list-style responses"},"country_name":{"type":"string","description":"Full country name (if available)"},"carrier":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mobile carrier name (if available)"},"line_type":{"anyOf":[{"type":"string","enum":["mobile","landline","voip","toll-free","unknown"]},{"type":"null"}],"description":"Type of phone line"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Geographic location (if available)"},"error":{"type":"string","description":"Validation or parsing error message"}},"required":[],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone/parse":{"post":{"summary":"Parse phone number","tags":["Phone Validation (Public)"],"description":"Parse phone number to extract components","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"Phone number (e.g., +41 79 123 45 67)"},"country_code":{"type":"string","pattern":"^[A-Z]{2,3}$","description":"Country code: alpha-2 or alpha-3 (e.g., CH, ABK)"}}}}},"required":true},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the phone number is valid"},"formatted":{"anyOf":[{"type":"object","properties":{"e164":{"type":"string"},"international":{"type":"string"},"national":{"type":"string"},"rfc3966":{"type":"string"}},"required":["e164","international","national","rfc3966"],"additionalProperties":false},{"type":"string"}],"description":"Formatted phone number payload (validate: all formats, format endpoint: requested single format)"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"national_number":{"type":"string","description":"National number without country prefix"},"extension":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone extension if present"},"calling_code":{"type":"string","description":"Country calling code (without + prefix)"},"type":{"anyOf":[{"type":"string","enum":["fixed_line","mobile","fixed_line_or_mobile","toll_free","premium_rate","shared_cost","voip","personal_number","pager","uan","voicemail","unknown"]},{"type":"null"}],"description":"Normalized line type from libphonenumber-js"},"countries":{"type":"array","items":{"type":"string"},"description":"Supported countries (countries endpoint)"},"count":{"type":"number","description":"Total result count for list-style responses"},"country_name":{"type":"string","description":"Full country name (if available)"},"carrier":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mobile carrier name (if available)"},"line_type":{"anyOf":[{"type":"string","enum":["mobile","landline","voip","toll-free","unknown"]},{"type":"null"}],"description":"Type of phone line"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Geographic location (if available)"},"error":{"type":"string","description":"Validation or parsing error message"}},"required":[],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone/region":{"post":{"summary":"Detect country from phone number","tags":["Phone Validation (Public)"],"description":"Auto-detect country code from phone number","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"Phone number (e.g., +41791234567)"}}}}},"required":true},"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the phone number is valid"},"formatted":{"anyOf":[{"type":"object","properties":{"e164":{"type":"string"},"international":{"type":"string"},"national":{"type":"string"},"rfc3966":{"type":"string"}},"required":["e164","international","national","rfc3966"],"additionalProperties":false},{"type":"string"}],"description":"Formatted phone number payload (validate: all formats, format endpoint: requested single format)"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"national_number":{"type":"string","description":"National number without country prefix"},"extension":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone extension if present"},"calling_code":{"type":"string","description":"Country calling code (without + prefix)"},"type":{"anyOf":[{"type":"string","enum":["fixed_line","mobile","fixed_line_or_mobile","toll_free","premium_rate","shared_cost","voip","personal_number","pager","uan","voicemail","unknown"]},{"type":"null"}],"description":"Normalized line type from libphonenumber-js"},"countries":{"type":"array","items":{"type":"string"},"description":"Supported countries (countries endpoint)"},"count":{"type":"number","description":"Total result count for list-style responses"},"country_name":{"type":"string","description":"Full country name (if available)"},"carrier":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mobile carrier name (if available)"},"line_type":{"anyOf":[{"type":"string","enum":["mobile","landline","voip","toll-free","unknown"]},{"type":"null"}],"description":"Type of phone line"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Geographic location (if available)"},"error":{"type":"string","description":"Validation or parsing error message"}},"required":[],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone/countries":{"get":{"summary":"Get supported countries","tags":["Phone Validation (Public)"],"description":"Get list of all ISO country codes supported by phone validation","security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the phone number is valid"},"formatted":{"anyOf":[{"type":"object","properties":{"e164":{"type":"string"},"international":{"type":"string"},"national":{"type":"string"},"rfc3966":{"type":"string"}},"required":["e164","international","national","rfc3966"],"additionalProperties":false},{"type":"string"}],"description":"Formatted phone number payload (validate: all formats, format endpoint: requested single format)"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"national_number":{"type":"string","description":"National number without country prefix"},"extension":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone extension if present"},"calling_code":{"type":"string","description":"Country calling code (without + prefix)"},"type":{"anyOf":[{"type":"string","enum":["fixed_line","mobile","fixed_line_or_mobile","toll_free","premium_rate","shared_cost","voip","personal_number","pager","uan","voicemail","unknown"]},{"type":"null"}],"description":"Normalized line type from libphonenumber-js"},"countries":{"type":"array","items":{"type":"string"},"description":"Supported countries (countries endpoint)"},"count":{"type":"number","description":"Total result count for list-style responses"},"country_name":{"type":"string","description":"Full country name (if available)"},"carrier":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mobile carrier name (if available)"},"line_type":{"anyOf":[{"type":"string","enum":["mobile","landline","voip","toll-free","unknown"]},{"type":"null"}],"description":"Type of phone line"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Geographic location (if available)"},"error":{"type":"string","description":"Validation or parsing error message"}},"required":[],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/phone/calling-code/{countryCode}":{"get":{"summary":"Get calling code for country","tags":["Phone Validation (Public)"],"description":"Get international calling code for a specific ISO country code","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2,3}$"},"in":"path","name":"countryCode","required":true,"description":"Country code: alpha-2 or alpha-3 (e.g., CH, ABK)"}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the phone number is valid"},"formatted":{"anyOf":[{"type":"object","properties":{"e164":{"type":"string"},"international":{"type":"string"},"national":{"type":"string"},"rfc3966":{"type":"string"}},"required":["e164","international","national","rfc3966"],"additionalProperties":false},{"type":"string"}],"description":"Formatted phone number payload (validate: all formats, format endpoint: requested single format)"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"national_number":{"type":"string","description":"National number without country prefix"},"extension":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone extension if present"},"calling_code":{"type":"string","description":"Country calling code (without + prefix)"},"type":{"anyOf":[{"type":"string","enum":["fixed_line","mobile","fixed_line_or_mobile","toll_free","premium_rate","shared_cost","voip","personal_number","pager","uan","voicemail","unknown"]},{"type":"null"}],"description":"Normalized line type from libphonenumber-js"},"countries":{"type":"array","items":{"type":"string"},"description":"Supported countries (countries endpoint)"},"count":{"type":"number","description":"Total result count for list-style responses"},"country_name":{"type":"string","description":"Full country name (if available)"},"carrier":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mobile carrier name (if available)"},"line_type":{"anyOf":[{"type":"string","enum":["mobile","landline","voip","toll-free","unknown"]},{"type":"null"}],"description":"Type of phone line"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Geographic location (if available)"},"error":{"type":"string","description":"Validation or parsing error message"}},"required":[],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/public/info-tags/":{"get":{"summary":"Get info tags by keys (public)","tags":["infotags"],"description":"Fetch system-wide info tag content by keys. Used by <pve-info-tag> component.","parameters":[{"schema":{"type":"string"},"in":"query","name":"keys","required":false},{"schema":{"type":"string","minLength":2,"maxLength":5},"in":"query","name":"locale","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string","pattern":"^[a-z0-9_.-]+$"},"title":{"type":"string"},"description":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false}},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","title","description","created_at","updated_at"]}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["data","total","limit","offset"]}}}}}}},"/api/v1/public/info-tags/{key}":{"get":{"summary":"Get info tag by key (public)","tags":["infotags"],"description":"Fetch a single info tag by key. Used by <pve-info-tag> component.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":5},"in":"query","name":"locale","required":false},{"schema":{"type":"string","pattern":"^[a-z0-9_.-]+$"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string","pattern":"^[a-z0-9_.-]+$"},"title":{"type":"string"},"description":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false}},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","title","description","created_at","updated_at"]}},"required":["data"]}}}}}}},"/api/v1/secure/stats/counts":{"get":{"summary":"Get entity counts","tags":["Stats"],"description":"Get counts for multiple entity types in a single call. Optimized for dashboard views.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9,]+$"},"in":"query","name":"entities","required":true,"description":"Comma-separated list of entity types to get counts for"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"spaces":{"type":"number","description":"Total number of spaces"},"resources":{"type":"number","description":"Total number of resources"},"tags":{"type":"number","description":"Total number of tags"},"categories":{"type":"number","description":"Total number of categories"},"users":{"type":"number","description":"Total number of users"},"groups":{"type":"number","description":"Total number of groups"},"contacts":{"type":"number","description":"Total number of contacts"},"mediaFiles":{"type":"number","description":"Total number of media files"},"tenants":{"type":"number","description":"Total number of tenants. System admin only."},"calendars":{"type":"number","description":"Total number of calendars"},"qrCodes":{"type":"number","description":"Total number of QR codes"},"typeDefinitions":{"type":"number","description":"Total number of type definitions"},"recentChanges24h":{"type":"object","properties":{"total":{"type":"number","description":"Total change events in the period"},"created":{"type":"number","description":"Create or add events in the period"},"updated":{"type":"number","description":"Update or modify events in the period"},"deleted":{"type":"number","description":"Delete or remove events in the period"}},"required":["total","created","updated","deleted"],"additionalProperties":false},"recentChanges7d":{"type":"object","properties":{"total":{"type":"number","description":"Total change events in the period"},"created":{"type":"number","description":"Create or add events in the period"},"updated":{"type":"number","description":"Update or modify events in the period"},"deleted":{"type":"number","description":"Delete or remove events in the period"}},"required":["total","created","updated","deleted"],"additionalProperties":false}},"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/":{"get":{"summary":"List tenants","tags":["Tenants"],"description":"Retrieve the tenants visible to the current user. System admins can see all tenants; other users see only their own tenant.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"tags":["Tenants"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","domain","ownerEmail","ownerPassword"],"properties":{"name":{"type":"string","minLength":2,"maxLength":255},"domain":{"type":"string","minLength":2,"maxLength":255,"pattern":"^[a-z0-9.-]+$"},"ownerEmail":{"type":"string","format":"email"},"ownerPassword":{"type":"string","minLength":8,"maxLength":100},"description":{"type":"string","maxLength":1000},"type":{"type":"string","enum":["trial","paid","enterprise"]},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string","maxLength":50},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"defaultLanguage":{"type":"string","pattern":"^[a-z]{2}$","description":"Default language (ISO 639-1, e.g., en, de, fr)"},"additionalLanguages":{"type":"array","items":{"type":"string","pattern":"^[a-z]{2}$"},"description":"Additional supported languages"},"settings":{"type":"object"}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}":{"get":{"summary":"Get tenant details","tags":["Tenants"],"description":"Retrieve the configuration and metadata for a specific tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"tags":["Tenants"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":255},"domain":{"type":"string","pattern":"^[a-z0-9-]+$","minLength":2,"maxLength":63},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"additional_languages":{"type":"array","items":{"type":"string","pattern":"^[a-z]{2}$"},"description":"Additional supported languages (ISO 639-1 codes)"},"settings":{"type":"object"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"tags":["Tenants"],"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"force","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Tenant successfully deleted"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/info":{"get":{"summary":"Get tenant onboarding information","tags":["Tenants"],"description":"Retrieve comprehensive tenant onboarding details including tenant, admin, API, group, and space information.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenant":{"type":"object","additionalProperties":true},"admin":{"type":"object","additionalProperties":true},"api":{"type":"object","additionalProperties":true},"groups":{"type":"array","items":{"type":"object","additionalProperties":true}},"spaces":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/language-sync-status":{"get":{"summary":"Get language sync status","tags":["Tenants"],"description":"Retrieve the current status of a tenant language sync job or list recent sync jobs for the tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"job_id","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"operation":{"type":"string","enum":["add","remove","comprehensive"]},"language_code":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"entities_processed":{"type":"integer"},"entities_total":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Error details"}},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","operation","language_code","status","entities_processed","entities_total","created_at","updated_at"]},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"operation":{"type":"string","enum":["add","remove","comprehensive"]},"language_code":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"entities_processed":{"type":"integer"},"entities_total":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Error details"}},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","operation","language_code","status","entities_processed","entities_total","created_at","updated_at"]}}]}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/language-sync/history":{"get":{"summary":"Get language sync history","tags":["Tenants"],"description":"Get paginated language sync job history with server-side filtering","parameters":[{"schema":{"type":"string","enum":["pending","running","completed","failed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"language","required":false,"description":"Language code (ISO 639-1)"},{"schema":{"type":"string","enum":["add","remove","comprehensive"]},"in":"query","name":"operation","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateFrom","required":false,"description":"Start date (ISO 8601)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateTo","required":false,"description":"End date (ISO 8601)"},{"schema":{"type":"number","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"operation":{"type":"string","enum":["add","remove"]},"language_code":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"entities_processed":{"type":"integer"},"entities_total":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","additionalProperties":true}},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","operation","language_code","status","entities_processed","entities_total","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/translation-coverage":{"get":{"summary":"Get translation coverage","tags":["Tenants"],"description":"Retrieve translation completeness across spaces, resources, categories, and tags for a tenant based on populated source fields versus configured additional tenant languages","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"spaces":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total entities in this tenant scope"},"translated":{"type":"integer","minimum":0,"description":"Entities whose populated source fields are fully translated across all configured additional tenant languages"},"missing":{"type":"integer","minimum":0,"description":"Entities with at least one missing translation for a populated source field in a configured additional tenant language"},"percentage":{"type":"integer","minimum":0,"maximum":100,"description":"Fully translated percentage rounded to a whole number"}},"required":["total","translated","missing","percentage"],"additionalProperties":false},"resources":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total entities in this tenant scope"},"translated":{"type":"integer","minimum":0,"description":"Entities whose populated source fields are fully translated across all configured additional tenant languages"},"missing":{"type":"integer","minimum":0,"description":"Entities with at least one missing translation for a populated source field in a configured additional tenant language"},"percentage":{"type":"integer","minimum":0,"maximum":100,"description":"Fully translated percentage rounded to a whole number"}},"required":["total","translated","missing","percentage"],"additionalProperties":false},"categories":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total entities in this tenant scope"},"translated":{"type":"integer","minimum":0,"description":"Entities whose populated source fields are fully translated across all configured additional tenant languages"},"missing":{"type":"integer","minimum":0,"description":"Entities with at least one missing translation for a populated source field in a configured additional tenant language"},"percentage":{"type":"integer","minimum":0,"maximum":100,"description":"Fully translated percentage rounded to a whole number"}},"required":["total","translated","missing","percentage"],"additionalProperties":false},"tags":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total entities in this tenant scope"},"translated":{"type":"integer","minimum":0,"description":"Entities whose populated source fields are fully translated across all configured additional tenant languages"},"missing":{"type":"integer","minimum":0,"description":"Entities with at least one missing translation for a populated source field in a configured additional tenant language"},"percentage":{"type":"integer","minimum":0,"maximum":100,"description":"Fully translated percentage rounded to a whole number"}},"required":["total","translated","missing","percentage"],"additionalProperties":false},"missingItems":{"type":"object","properties":{"spaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["null","string"]},"baseLanguage":{"type":["null","string"]},"missingLanguages":{"type":"array","items":{"type":"string"}},"missingFieldsByLanguage":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","enum":["name","description"]}}}},"required":["id","title","description","baseLanguage","missingLanguages","missingFieldsByLanguage"],"additionalProperties":false}},"resources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["null","string"]},"baseLanguage":{"type":["null","string"]},"missingLanguages":{"type":"array","items":{"type":"string"}},"missingFieldsByLanguage":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","enum":["name","description"]}}}},"required":["id","title","description","baseLanguage","missingLanguages","missingFieldsByLanguage"],"additionalProperties":false}},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["null","string"]},"baseLanguage":{"type":["null","string"]},"missingLanguages":{"type":"array","items":{"type":"string"}},"missingFieldsByLanguage":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","enum":["name","description"]}}}},"required":["id","title","description","baseLanguage","missingLanguages","missingFieldsByLanguage"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["null","string"]},"baseLanguage":{"type":["null","string"]},"missingLanguages":{"type":"array","items":{"type":"string"}},"missingFieldsByLanguage":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","enum":["name","description"]}}}},"required":["id","title","description","baseLanguage","missingLanguages","missingFieldsByLanguage"],"additionalProperties":false}}},"required":["spaces","resources","categories","tags"],"additionalProperties":false}},"required":["spaces","resources","categories","tags","missingItems"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/env":{"get":{"summary":"Export tenant environment configuration","tags":["Tenants"],"description":"Export the tenant configuration as a downloadable .env file.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/json":{"get":{"summary":"Export tenant JSON configuration","tags":["Tenants"],"description":"Export the tenant configuration as a downloadable JSON file.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/oauth-redirect-uris":{"get":{"summary":"Get OAuth redirect URIs","tags":["Tenants"],"description":"Returns OAuth redirect URIs computed from verified custom domains for this tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"redirect_uris":{"type":"array","items":{"type":"string","format":"uri","description":"OAuth redirect URI (HTTPS only, format: https://{domain}/auth/v1/callback)"},"description":"OAuth redirect URIs computed from verified custom domains (HTTPS only)"}},"required":["redirect_uris"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/domains":{"get":{"summary":"List tenant domains","tags":["Tenants"],"description":"Returns custom domains configured for a tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Domain configuration unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this domain belongs to"},"domain":{"type":"string","description":"Custom domain (e.g., api.wishtree.online)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api (platform API root, environment-specific target resolved by deployment)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Verification status: pending, verifying, verified, failed, expired"},"verification_token":{"type":["null","string"],"description":"Unique token for domain verification (32-char alphanumeric)"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"},"verified_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when domain was successfully verified (ISO 8601)"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"SSL certificate status: none, pending, issued, failed, expiring, expired"},"ssl_issued_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate was issued (ISO 8601)"},"ssl_expires_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate expires (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","domain","domain_type","status","verification_method","ssl_status","settings","created_at","updated_at"],"additionalProperties":false},"description":"Array of tenant domain objects"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create tenant domain","tags":["Tenants"],"description":"Creates a custom domain entry for the specified tenant and starts its managed lifecycle.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["domain","domain_type"],"properties":{"domain":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$","description":"Custom domain (valid hostname format, no protocol, no path)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method (default: cname)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Domain configuration unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this domain belongs to"},"domain":{"type":"string","description":"Custom domain (e.g., api.wishtree.online)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api (platform API root, environment-specific target resolved by deployment)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Verification status: pending, verifying, verified, failed, expired"},"verification_token":{"type":["null","string"],"description":"Unique token for domain verification (32-char alphanumeric)"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"},"verified_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when domain was successfully verified (ISO 8601)"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"SSL certificate status: none, pending, issued, failed, expiring, expired"},"ssl_issued_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate was issued (ISO 8601)"},"ssl_expires_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate expires (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","domain","domain_type","status","verification_method","ssl_status","settings","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/domains/{domainId}":{"get":{"summary":"Get tenant domain","tags":["Tenants"],"description":"Returns a single custom domain configured for the specified tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Domain configuration unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this domain belongs to"},"domain":{"type":"string","description":"Custom domain (e.g., api.wishtree.online)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api (platform API root, environment-specific target resolved by deployment)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Verification status: pending, verifying, verified, failed, expired"},"verification_token":{"type":["null","string"],"description":"Unique token for domain verification (32-char alphanumeric)"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"},"verified_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when domain was successfully verified (ISO 8601)"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"SSL certificate status: none, pending, issued, failed, expiring, expired"},"ssl_issued_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate was issued (ISO 8601)"},"ssl_expires_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate expires (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","domain","domain_type","status","verification_method","ssl_status","settings","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update tenant domain","tags":["Tenants"],"description":"Updates the hostname, status, or verification-related settings for a tenant domain.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$","description":"Update domain (valid hostname format)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Update verification status"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Update verification method"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"Update SSL certificate status"},"ssl_issued_at":{"type":["string","null"],"format":"date-time","description":"Update SSL certificate issued timestamp (ISO 8601)"},"ssl_expires_at":{"type":["string","null"],"format":"date-time","description":"Update SSL certificate expiration timestamp (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Update domain-specific settings (JSONB)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Domain configuration unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this domain belongs to"},"domain":{"type":"string","description":"Custom domain (e.g., api.wishtree.online)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api (platform API root, environment-specific target resolved by deployment)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Verification status: pending, verifying, verified, failed, expired"},"verification_token":{"type":["null","string"],"description":"Unique token for domain verification (32-char alphanumeric)"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"},"verified_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when domain was successfully verified (ISO 8601)"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"SSL certificate status: none, pending, issued, failed, expiring, expired"},"ssl_issued_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate was issued (ISO 8601)"},"ssl_expires_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate expires (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","domain","domain_type","status","verification_method","ssl_status","settings","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete tenant domain","tags":["Tenants"],"description":"Deletes a custom domain from the specified tenant configuration.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"domainId","required":true}],"responses":{"204":{"description":"Tenant domain deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/domains/{domainId}/verify":{"post":{"summary":"Verify tenant domain","tags":["Tenants"],"description":"Runs the domain verification workflow and returns the latest verification result.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"domainId":{"type":"string","format":"uuid","description":"Domain configuration ID"},"domain":{"type":"string","description":"Domain being verified"},"verified":{"type":"boolean","description":"Whether verification succeeded"},"method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method used"},"details":{"type":"object","properties":{"cnameTarget":{"type":["null","string"],"description":"Actual CNAME target found"},"expectedTarget":{"type":"string","description":"Expected CNAME target"},"txtRecordFound":{"type":["null","boolean"],"description":"Whether TXT record was found"},"httpFileContent":{"type":["null","string"],"description":"HTTP verification file content"}},"required":["expectedTarget"]},"error":{"type":["null","object"],"properties":{"code":{"type":"string","enum":["DNS_LOOKUP_FAILED","CNAME_MISMATCH","TXT_NOT_FOUND","HTTP_NOT_FOUND","TIMEOUT"],"description":"Error code if verification failed"},"message":{"type":"string","description":"Human-readable error message"}}},"verifiedAt":{"type":["null","string"],"format":"date-time","description":"Timestamp when verification completed (ISO 8601)"}},"required":["domainId","domain","verified","method","details"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/domains/{domainId}/verification-instructions":{"get":{"summary":"Get tenant domain verification instructions","tags":["Tenants"],"description":"Returns DNS or platform setup instructions required to complete tenant domain verification.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Domain to configure"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api"},"method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method"},"instructions":{"type":"object","properties":{"cname":{"type":"object","properties":{"record_type":{"type":"string","description":"DNS record type (CNAME)"},"name":{"type":"string","description":"DNS record name (subdomain)"},"value":{"type":"string","description":"DNS record value (target)"},"ttl":{"type":"number","description":"Recommended TTL in seconds"}}},"txt":{"type":"object","properties":{"record_type":{"type":"string","description":"DNS record type (TXT)"},"name":{"type":"string","description":"DNS record name"},"value":{"type":"string","description":"Verification token"}}},"http":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL to create verification file"},"content":{"type":"string","description":"File content to place at URL"}}}}}},"required":["domain","domain_type","method","instructions"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/developer-config":{"get":{"summary":"Get developer configuration information","tags":["Tenants"],"description":"Returns consolidated developer configuration including tenant info, admin user, API endpoints, configuration counts, and domain information.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/lifecycle/activate":{"post":{"summary":"Activate tenant","tags":["Tenants"],"description":"Activate tenant (pending → trial, or inactive → active)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Reason for activation (audit trail)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/lifecycle/upgrade":{"post":{"summary":"Upgrade tenant","tags":["Tenants"],"description":"Upgrade tenant type (trial → paid → enterprise)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["target_type"],"properties":{"target_type":{"type":"string","enum":["paid","enterprise"],"description":"Target plan type"},"reason":{"type":"string","maxLength":500,"description":"Reason for upgrade (audit trail)"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/lifecycle/suspend":{"post":{"summary":"Suspend tenant","tags":["Tenants"],"description":"Suspend tenant (active → inactive)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Reason for suspension (audit trail)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/lifecycle/reactivate":{"post":{"summary":"Reactivate tenant","tags":["Tenants"],"description":"Reactivate tenant (inactive → active)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Reason for reactivation (audit trail)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/lifecycle/archive":{"post":{"summary":"Archive tenant","tags":["Tenants"],"description":"Archive tenant (inactive → retired)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Reason for archiving (audit trail)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/lifecycle/history":{"get":{"summary":"Get tenant lifecycle history","tags":["Tenants"],"description":"Get lifecycle history (audit trail) for tenant","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"from_status":{"type":"string"},"to_status":{"type":"string"},"from_type":{"type":"string"},"to_type":{"type":"string"},"action":{"type":"string"},"reason":{"type":"string","nullable":true},"performed_by":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}},"required":["tenantId","from_status","to_status","action","performed_by","created_at"]}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/settings":{"get":{"summary":"Get all tenant settings","tags":["Tenant Settings"],"description":"Retrieve all settings categories for a tenant","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"general":{"type":"object","properties":{"timezone":{"type":"string","description":"IANA timezone (e.g., Europe/Zurich)","pattern":"^[A-Za-z_]+/[A-Za-z_]+$"},"locale":{"type":"string","description":"Locale code in BCP 47 format","pattern":"^[a-z]{2}-[A-Z]{2}$"},"date_format":{"type":"string","enum":["YYYY-MM-DD","DD.MM.YYYY","MM/DD/YYYY"]},"time_format":{"type":"string","enum":["12h","24h"]},"user_name_format":{"type":"string","enum":["first-middle-last","first-last","last-first","last-first-middle"],"description":"Tenant-specific ordering for generated user fullName values"}},"required":["timezone","locale","date_format","time_format","user_name_format"],"additionalProperties":false},"limits":{"type":"object","properties":{"max_users":{"type":"number","description":"Maximum users (-1 = unlimited)"},"max_spaces":{"type":"number","description":"Maximum spaces (-1 = unlimited)"},"max_resources":{"type":"number","description":"Maximum resources (-1 = unlimited)"},"max_storage_gb":{"type":"number","description":"Maximum storage in GB"},"max_api_calls_per_day":{"type":"number","description":"Maximum API calls per day"}},"required":["max_users","max_spaces","max_resources","max_storage_gb","max_api_calls_per_day"],"additionalProperties":false},"integrations":{"type":"object","properties":{"calendar":{"type":"object","properties":{"provider":{"type":"string","description":"Integration provider name"},"api_key_vault_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to encrypted API key in Supabase Vault"},"enabled":{"type":"boolean","description":"Whether integration is active"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration"}},"required":["provider","enabled"],"additionalProperties":false,"description":"Calendar integration (Google, Outlook, iCal)"},"billing":{"type":"object","properties":{"provider":{"type":"string","description":"Integration provider name"},"api_key_vault_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to encrypted API key in Supabase Vault"},"enabled":{"type":"boolean","description":"Whether integration is active"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration"}},"required":["provider","enabled"],"additionalProperties":false,"description":"Billing integration (Stripe, PayPal)"},"email_sendgrid":{"type":"object","properties":{"provider":{"type":"string","description":"Integration provider name"},"api_key_vault_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to encrypted API key in Supabase Vault"},"enabled":{"type":"boolean","description":"Whether integration is active"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration"}},"required":["provider","enabled"],"additionalProperties":false,"description":"SendGrid email provider"},"email_smtp":{"type":"object","properties":{"provider":{"type":"string","description":"Integration provider name"},"api_key_vault_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to encrypted API key in Supabase Vault"},"enabled":{"type":"boolean","description":"Whether integration is active"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration"}},"required":["provider","enabled"],"additionalProperties":false,"description":"SMTP email provider"},"sms_twilio":{"type":"object","properties":{"provider":{"type":"string","description":"Integration provider name"},"api_key_vault_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to encrypted API key in Supabase Vault"},"enabled":{"type":"boolean","description":"Whether integration is active"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration"}},"required":["provider","enabled"],"additionalProperties":false,"description":"Twilio SMS provider"},"sms_mail2sms":{"type":"object","properties":{"provider":{"type":"string","description":"Integration provider name"},"api_key_vault_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to encrypted API key in Supabase Vault"},"enabled":{"type":"boolean","description":"Whether integration is active"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration"}},"required":["provider","enabled"],"additionalProperties":false,"description":"Mail2SMS provider"}},"additionalProperties":{"type":"object","properties":{"provider":{"type":"string","description":"Integration provider name"},"api_key_vault_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to encrypted API key in Supabase Vault"},"enabled":{"type":"boolean","description":"Whether integration is active"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration"}},"required":["provider","enabled"],"additionalProperties":false},"description":"Extensible integration configurations (email, SMS, calendar, billing, webhooks)"},"notifications":{"type":"object","properties":{"email_notifications":{"type":"boolean","description":"Enable email notifications"},"sms_notifications":{"type":"boolean","description":"Enable SMS notifications"},"webhook_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Webhook endpoint for notifications"}},"required":["email_notifications","sms_notifications"],"additionalProperties":false},"security":{"type":"object","properties":{"allowed_oauth_redirect_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"List of allowed frontend URLs for OAuth redirects (e.g., https://app.tenant.com)"},"default_oauth_redirect_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Default redirect URL for OAuth (must be in allowed list)"},"allowed_cors_origins":{"type":"array","items":{"type":"string"},"description":"Additional CORS origins allowed for this tenant (supports wildcards like *.tenant.com)"},"oauth_providers_enabled":{"type":"array","items":{"type":"string","enum":["google","microsoft","apple","facebook","github"]},"description":"OAuth providers enabled for this tenant (empty = use system defaults)"},"password_auth_enabled":{"type":"boolean","description":"Whether email/password authentication is enabled for this tenant"},"mfa_required":{"type":"boolean","description":"Whether MFA is required for all users in this tenant"},"require_invitation":{"type":"boolean","description":"Whether users must have an invitation to register. System tenant has this enabled by default."},"allow_self_registration":{"type":"boolean","description":"Whether users can self-register without invitation (opposite of require_invitation for convenience)"}},"additionalProperties":false}},"required":["general","limits","integrations","notifications","security"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/settings/{category}":{"get":{"summary":"Get category settings","tags":["Tenant Settings"],"description":"Retrieve settings for a specific category","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"},{"schema":{"type":"string","enum":["general","limits","integrations","notifications","security"]},"in":"path","name":"category","required":true,"description":"Settings category"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["general","limits","integrations","notifications","security"]},"settings":{},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["tenantId","category","settings"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update category settings","tags":["Tenant Settings"],"description":"Update settings for a specific category (partial merge)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","additionalProperties":true,"description":"Partial settings update (merges with existing). Category-specific validation in service layer."}},"required":["settings"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"},{"schema":{"type":"string","enum":["general","limits","integrations","notifications","security"]},"in":"path","name":"category","required":true,"description":"Settings category"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["general","limits","integrations","notifications","security"]},"settings":{},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["tenantId","category","settings"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/settings/{category}/reset":{"post":{"summary":"Reset settings to defaults","tags":["Tenant Settings"],"description":"Reset category settings to default values based on tenant type","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_type":{"type":"string","enum":["trial","paid","enterprise"],"description":"Tenant type for default template (default: trial)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"},{"schema":{"type":"string","enum":["general","limits","integrations","notifications","security"]},"in":"path","name":"category","required":true,"description":"Settings category"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["general","limits","integrations","notifications","security"]},"settings":{},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["tenantId","category","settings"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/settings/history":{"get":{"summary":"Get settings history","tags":["Tenant Settings"],"description":"Retrieve audit trail of settings changes","parameters":[{"schema":{"type":"string","enum":["general","limits","integrations","notifications"]},"in":"query","name":"category","required":false,"description":"Filter by category (optional)"},{"schema":{"type":"number","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false,"description":"Number of history entries to return"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["general","limits","integrations","notifications","security"]},"settings_before":{"anyOf":[{"type":"object","additionalProperties":true,"description":"Settings before change (JSONB)"},{"type":"null"}],"description":"Settings before change (null on first create)"},"settings_after":{"type":"object","additionalProperties":true,"description":"Settings after change (JSONB)"},"changed_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"User who made the change"},"changed_at":{"type":"string","format":"date-time"},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"ip_address":{"anyOf":[{"type":"string","format":"ipv4"},{"type":"string","format":"ipv6"},{"type":"null"}]}},"required":["id","tenantId","category","settings_after","changed_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/metrics/snapshot":{"get":{"summary":"Get metrics snapshot","tags":["Tenant Metrics"],"description":"Retrieve real-time snapshot of current tenant metrics","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"tenantName":{"type":"string","description":"Tenant name"},"users":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total number of users"},"active":{"type":"integer","minimum":0,"description":"Active users (last 30 days)"}},"required":["total","active"],"additionalProperties":false},"spaces":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total number of spaces"},"active":{"type":"integer","minimum":0,"description":"Active spaces"}},"required":["total","active"],"additionalProperties":false},"resources":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total number of resources"},"active":{"type":"integer","minimum":0,"description":"Active resources"}},"required":["total","active"],"additionalProperties":false},"storage":{"type":"object","properties":{"usedBytes":{"type":"integer","minimum":0,"description":"Storage used in bytes"},"usedGB":{"type":"number","minimum":0,"description":"Storage used in gigabytes"}},"required":["usedBytes","usedGB"],"additionalProperties":false},"snapshotAt":{"type":"string","format":"date-time","description":"Timestamp of snapshot"}},"required":["tenantId","tenantName","users","spaces","resources","storage","snapshotAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/metrics/daily":{"get":{"summary":"Get daily metrics","tags":["Tenant Metrics"],"description":"Retrieve historical daily metrics for a tenant (max 90 days)","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"startDate","required":false,"description":"Start date (ISO 8601, inclusive)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"endDate","required":false,"description":"End date (ISO 8601, inclusive)"},{"schema":{"type":"integer","minimum":1,"maximum":365,"default":90},"in":"query","name":"limit","required":false,"description":"Maximum records to return"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Metrics record UUID"},"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"metricDate":{"type":"string","format":"date","description":"Metrics date (ISO 8601)"},"users":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total number of users"},"active":{"type":"integer","minimum":0,"description":"Active users (last 30 days)"}},"required":["total","active"],"additionalProperties":false},"spaces":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total number of spaces"},"active":{"type":"integer","minimum":0,"description":"Active spaces"}},"required":["total","active"],"additionalProperties":false},"resources":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total number of resources"},"active":{"type":"integer","minimum":0,"description":"Active resources"}},"required":["total","active"],"additionalProperties":false},"storage":{"type":"object","properties":{"usedBytes":{"type":"integer","minimum":0,"description":"Storage used in bytes"},"usedGB":{"type":"number","minimum":0,"description":"Storage used in gigabytes"}},"required":["usedBytes","usedGB"],"additionalProperties":false},"apiCalls":{"type":["null","integer"],"minimum":0,"description":"API calls count (if tracked)"},"createdAt":{"type":"string","format":"date-time","description":"Record creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Record update timestamp"}},"required":["id","tenantId","metricDate","users","spaces","resources","storage","createdAt","updatedAt"],"additionalProperties":false},"description":"Array of daily metrics (sorted by date desc)"}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/metrics/monthly":{"get":{"summary":"Get monthly metrics","tags":["Tenant Metrics"],"description":"Retrieve historical monthly metrics for a tenant (max 12 months)","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":24,"default":12},"in":"query","name":"limit","required":false,"description":"Maximum records to return"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Metrics record UUID"},"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"year":{"type":"integer","minimum":2024,"description":"Year"},"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month (1-12)"},"users":{"type":"object","properties":{"average":{"type":"integer","minimum":0,"description":"Average total users"},"peak":{"type":"integer","minimum":0,"description":"Peak users in any day"}},"required":["average","peak"],"additionalProperties":false},"spaces":{"type":"object","properties":{"average":{"type":"integer","minimum":0,"description":"Average total spaces"},"peak":{"type":"integer","minimum":0,"description":"Peak spaces in any day"}},"required":["average","peak"],"additionalProperties":false},"resources":{"type":"object","properties":{"average":{"type":"integer","minimum":0,"description":"Average total resources"},"peak":{"type":"integer","minimum":0,"description":"Peak resources in any day"}},"required":["average","peak"],"additionalProperties":false},"storage":{"type":"object","properties":{"averageBytes":{"type":"integer","minimum":0,"description":"Average storage in bytes"},"averageGB":{"type":"number","minimum":0,"description":"Average storage in GB"},"peakBytes":{"type":"integer","minimum":0,"description":"Peak storage in bytes"},"peakGB":{"type":"number","minimum":0,"description":"Peak storage in GB"}},"required":["averageBytes","averageGB","peakBytes","peakGB"],"additionalProperties":false},"totalApiCalls":{"type":["null","integer"],"minimum":0,"description":"Total API calls for the month"},"createdAt":{"type":"string","format":"date-time","description":"Record creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Record update timestamp"}},"required":["id","tenantId","year","month","users","spaces","resources","storage","createdAt","updatedAt"],"additionalProperties":false},"description":"Array of monthly metrics (sorted by year/month desc)"}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/metrics/quota-warnings":{"get":{"summary":"Get quota warnings","tags":["Tenant Metrics"],"description":"Check quota warnings for a tenant (compares usage against limits)","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":90},"in":"query","name":"threshold","required":false,"description":"Warning threshold percentage"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"warnings":{"type":"array","items":{"type":"object","properties":{"resource":{"type":"string","enum":["users","spaces","resources","storage"],"description":"Resource type"},"current":{"type":"number","minimum":0,"description":"Current usage"},"limit":{"type":"number","minimum":0,"description":"Configured limit"},"percentage":{"type":"number","minimum":0,"maximum":100,"description":"Usage percentage"},"threshold":{"type":"number","minimum":0,"maximum":100,"description":"Warning threshold"},"exceeded":{"type":"boolean","description":"Whether limit is exceeded"}},"required":["resource","current","limit","percentage","threshold","exceeded"],"additionalProperties":false},"description":"Array of quota warnings (only resources at/above threshold)"},"checkedAt":{"type":"string","format":"date-time","description":"Timestamp of check"}},"required":["tenantId","warnings","checkedAt"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/dashboard":{"get":{"summary":"Get tenant dashboard","tags":["Tenants"],"description":"Get all tenant dashboard data in one call: tenant info, metrics, storage, recent activity, and language sync status","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Tenant name"},"slug":{"type":"string","description":"URL-friendly identifier"},"domain":{"type":"string","description":"Tenant domain"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant description"},"type":{"type":"string","enum":["system","trial","paid","enterprise"],"description":"Subscription type"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Primary contact email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary contact phone"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-specific settings and configuration"},"default_language":{"type":"string","description":"Default language (ISO 639-1, immutable after creation)"},"additional_languages":{"type":"array","items":{"type":"string"},"description":"Additional supported languages (ISO 639-1 codes)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","domain","status","type","settings","default_language","additional_languages","created_at","updated_at"],"additionalProperties":false},"metrics":{"type":"object","properties":{"users":{"type":"object","properties":{"total":{"type":"number"},"active":{"type":"number"},"trend":{"type":"number","description":"Percentage change vs last period"}},"required":["total","active"]},"spaces":{"type":"object","properties":{"total":{"type":"number"},"active":{"type":"number"},"trend":{"type":"number"}},"required":["total","active"]},"resources":{"type":"object","properties":{"total":{"type":"number"},"trend":{"type":"number"}},"required":["total"]},"apiRequests":{"type":"object","properties":{"last30d":{"type":"number"}},"required":["last30d"]}},"required":["users","spaces","resources","apiRequests"]},"storage":{"type":"object","properties":{"used":{"type":"number","description":"Storage used in bytes"},"limit":{"type":"number","description":"Storage limit in bytes"},"percent":{"type":"number","description":"Usage percentage"}},"required":["used","limit","percent"]},"recentActivity":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"entity_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"required":["type","entity_id","entity_type","timestamp"]},"description":"Last 10 activities"},"languageSync":{"type":"object","properties":{"activeJobs":{"type":"number"},"lastSync":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["activeJobs"]}},"required":["tenant","metrics","storage","recentActivity","languageSync"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/log-retention":{"get":{"summary":"Get tenant log retention policy","tags":["Tenants"],"description":"Retrieve the current log retention policy for the specified tenant, including the default when no explicit setting exists.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"retention_days":{"type":"number","enum":[30,60,90]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"tags":["Tenants"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["retention_days"],"properties":{"retention_days":{"type":"number","enum":[30,60,90]}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"retention_days":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/rate-limits":{"get":{"summary":"List rate limit configurations","tags":["Tenant Rate Limits"],"description":"Get all rate limit configurations for a tenant","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"endpoint_pattern":{"type":"string"},"max_requests":{"type":"number"},"window_seconds":{"type":"number"},"scope_type":{"type":"string","enum":["per_ip","per_user","per_device","per_app_account","per_tenant"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","endpoint_pattern","max_requests","window_seconds","scope_type","enabled","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create rate limit configuration","tags":["Tenant Rate Limits"],"description":"Create a new rate limit configuration for a tenant","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_pattern":{"type":"string"},"max_requests":{"type":"number","minimum":1},"window_seconds":{"type":"number","minimum":1},"scope_type":{"type":"string","enum":["per_ip","per_user","per_device","per_app_account","per_tenant"]},"enabled":{"type":"boolean","default":true}},"required":["endpoint_pattern","max_requests","window_seconds","scope_type"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"endpoint_pattern":{"type":"string"},"max_requests":{"type":"number"},"window_seconds":{"type":"number"},"scope_type":{"type":"string","enum":["per_ip","per_user","per_device","per_app_account","per_tenant"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","endpoint_pattern","max_requests","window_seconds","scope_type","enabled","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenants/{id}/rate-limits/{limitId}":{"get":{"summary":"Get rate limit configuration","tags":["Tenant Rate Limits"],"description":"Get a single rate limit configuration by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"limitId","required":true,"description":"Rate limit configuration ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"endpoint_pattern":{"type":"string"},"max_requests":{"type":"number"},"window_seconds":{"type":"number"},"scope_type":{"type":"string","enum":["per_ip","per_user","per_device","per_app_account","per_tenant"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","endpoint_pattern","max_requests","window_seconds","scope_type","enabled","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update rate limit configuration","tags":["Tenant Rate Limits"],"description":"Update an existing rate limit configuration","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"endpoint_pattern":{"type":"string"},"max_requests":{"type":"number","minimum":1},"window_seconds":{"type":"number","minimum":1},"scope_type":{"type":"string","enum":["per_ip","per_user","per_device","per_app_account","per_tenant"]},"enabled":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"limitId","required":true,"description":"Rate limit configuration ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"endpoint_pattern":{"type":"string"},"max_requests":{"type":"number"},"window_seconds":{"type":"number"},"scope_type":{"type":"string","enum":["per_ip","per_user","per_device","per_app_account","per_tenant"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","endpoint_pattern","max_requests","window_seconds","scope_type","enabled","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete rate limit configuration","tags":["Tenant Rate Limits"],"description":"Delete a rate limit configuration","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tenant ID"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"limitId","required":true,"description":"Rate limit configuration ID"}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/":{"get":{"summary":"List users","tags":["Users"],"description":"Retrieve paginated users with optional search and tenant filtering based on the caller's access scope.","parameters":[{"schema":{"type":"number","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Records per page (default: 50)"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset","required":false,"description":"Pagination offset (default: 0)"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search by email or name"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false,"description":"Filter by tenant ID (system admin only)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false}},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"tags":["Users"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"displayName":{"type":"string"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"settings":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false}},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/{id}":{"get":{"summary":"Get user details","tags":["Users"],"description":"Retrieve the full profile information for a specific user in the current tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false}},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update user profile","tags":["Users"],"description":"Update user profile information (first name, last name, display name, locale)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"displayName":{"type":["string","null"]},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"settings":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false}},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete user","tags":["Users"],"description":"Delete a user including auth, public profile, memberships, group links, and entity links.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"User UUID"}],"responses":{"204":{"description":"User deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/{id}/tenants/{tenantId}":{"delete":{"summary":"Remove user tenant link","tags":["Users"],"description":"Unlink a user from a selected tenant. System admins can target any tenant; tenant admins are limited to their active tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"User UUID"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"tenantId","required":true,"description":"Tenant UUID to unlink from the user"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/{id}/reset-password":{"post":{"summary":"Reset user password","tags":["Users"],"description":"Generate a temporary password for a user. The current password stops working immediately.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["generated","custom"],"default":"generated","description":"Whether to generate a temporary password or set a custom one directly"},"password":{"anyOf":[{"type":"string","minLength":8},{"type":"null"}],"description":"Required when mode is custom"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"User UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"mode":{"type":"string","enum":["generated","custom"],"description":"How the password reset was performed"},"message":{"type":"string","description":"Operator-facing result summary"},"password":{"anyOf":[{"type":"string","minLength":8,"description":"Temporary password returned once after a generated admin reset"},{"type":"null"}]}},"required":["mode","message","password"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/{id}/context":{"get":{"summary":"Get user context","tags":["Users"],"description":"Get user with all related data: groups, permissions, and recent activity","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"User UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false},"description":"All tenant memberships linked to this user account"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local first name (e.g., Thai: สมชาย)"},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local middle name (optional)"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local last name (e.g., Thai: ใจดี)"},"displayName":{"type":"string","description":"Public display name. Never null; falls back to generated fullName."},"fullName":{"type":"string","description":"Generated full name using tenant-specific name ordering."},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Resolved avatar URL from selected source"},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at"],"additionalProperties":false},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"role":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"required":["id","name","permissions"]}},"permissions":{"type":"array","items":{"type":"object","properties":{"resource":{"type":"string"},"action":{"type":"string"}},"required":["resource","action"]},"description":"Flattened list of all user permissions"},"recentActivity":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"entity_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}},"required":["type","entity_id","entity_type","timestamp"]},"description":"Last 5 activities"}},"required":["user","groups","permissions","recentActivity"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/{id}/status":{"patch":{"summary":"Update user status","tags":["Users"],"description":"Update the operational status for a specific user","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"}},"required":["status"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"User UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false}},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/{id}/email-verification":{"patch":{"summary":"Update email verification","tags":["Users"],"description":"Mark a user email verification task as verified or pending without relying on Supabase auth confirmation","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean"}},"required":["verified"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"User UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false}},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/groups/":{"get":{"summary":"List groups","tags":["Groups"],"description":"Retrieve paginated groups with optional tenant, membership, tag, category, and date filters.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false,"description":"Filter by tenant ID (system admin only)"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Full-text search (name, description)"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"tag_ids","required":false,"description":"Filter by tag IDs"},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"tag_names","required":false,"description":"Filter by tag names (normalized)"},{"schema":{"type":"boolean"},"in":"query","name":"match_all_tags","required":false,"description":"true = AND, false = OR (default: false)"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"category_ids","required":false,"description":"Filter by category IDs"},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"category_keys","required":false,"description":"Filter by category keys"},{"schema":{"type":"boolean"},"in":"query","name":"match_all_categories","required":false,"description":"true = AND, false = OR (default: false)"},{"schema":{"type":"boolean"},"in":"query","name":"include_children","required":false,"description":"Include hierarchical category children (default: false)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_after","required":false,"description":"Filter by created_at >= ISO 8601 date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_before","required":false,"description":"Filter by created_at <= ISO 8601 date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_after","required":false,"description":"Filter by updated_at >= ISO 8601 date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_before","required":false,"description":"Filter by updated_at <= ISO 8601 date"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"user_id","required":false,"description":"Filter by user membership"},{"schema":{"type":"number","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Records per page (default: 50, max: 100)"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset","required":false,"description":"Pagination offset (default: 0)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Group name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Group description"},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission codes"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","permissions","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/groups/{id}":{"get":{"summary":"Get group details","tags":["Groups"],"description":"Retrieve a specific group and its current configuration by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Group name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Group description"},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission codes"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","permissions","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"put":{"tags":["Groups"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"permissions":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Group name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Group description"},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission codes"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","permissions","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"tags":["Groups"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/groups/create":{"post":{"tags":["Groups"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"permissions":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Group name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Group description"},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission codes"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","permissions","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/groups/{id}/members":{"post":{"tags":["Group Members"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string","format":"uuid"}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"get":{"summary":"List group members","tags":["Group Members"],"description":"Retrieve all users currently assigned to a specific group.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["user_id","email","displayName","fullName","created_at"]}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/groups/{id}/members/{userId}":{"delete":{"tags":["Group Members"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"userId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/groups/users/{userId}/permissions":{"get":{"summary":"Get user permissions","tags":["User Groups"],"description":"Retrieve the effective permission list for a specific user within the current tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"userId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"},"description":"Array of permission codes for the user"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/groups/export":{"get":{"summary":"Export groups","tags":["Groups"],"description":"Export groups to Excel/CSV/TSV","parameters":[{"schema":{"type":"string","enum":["xlsx","csv","tsv","json","json-schema"],"default":"xlsx"},"in":"query","name":"format","required":false,"description":"Export file format (xlsx, csv, tsv)"},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeExample","required":false,"description":"Include example row if data is empty"},{"schema":{"type":"number","minimum":1,"maximum":10000,"default":10000},"in":"query","name":"limit","required":false,"description":"Maximum number of rows to export"},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Offset for pagination"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Binary file download","content":{"application/json":{"schema":{"description":"Binary file download","type":"string","format":"binary"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/groups/import":{"post":{"summary":"Import groups","tags":["Groups"],"description":"Import groups from Excel/CSV/TSV file","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether import completed without critical errors"},"dryRun":{"type":"boolean","description":"Whether this was a validation-only dry run"},"entityType":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"],"description":"Entity type that was imported"},"stats":{"type":"object","properties":{"created":{"type":"number","description":"Number of entities created"},"updated":{"type":"number","description":"Number of entities updated"},"skipped":{"type":"number","description":"Number of entities skipped (merge strategy)"},"duplicates":{"type":"number","description":"Number of duplicate entries detected"},"errors":{"type":"number","description":"Number of rows with errors"}},"required":["created","updated","skipped","duplicates","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","description":"Row number (1-based, including header)"},"column":{"type":"string","description":"Column name where error occurred"},"value":{"type":"string","description":"Value that caused the error"},"identifier":{"type":"string","description":"Entity identifier (name, key, id)"},"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["INVALID_FORMAT","REQUIRED_FIELD","INVALID_UUID","DUPLICATE_ENTRY","REFERENCE_NOT_FOUND","VALIDATION_ERROR","IMPORT_ERROR","FILE_ERROR"]}},"required":["identifier","message","code"],"additionalProperties":false},"description":"Detailed error information per row"},"processedRows":{"type":"number","description":"Total number of rows processed"},"totalRows":{"type":"number","description":"Total number of rows in file"}},"required":["success","dryRun","entityType","stats","warnings","errors"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/iam/":{"get":{"summary":"Get IAM overview","tags":["System"],"description":"Retrieve the current user's IAM overview including groups, permissions, and admin flags.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"userId":{"type":"string"},"tenantId":{"type":"string"},"email":{"type":"string"},"isSystemAdmin":{"type":"boolean"},"isTenantAdmin":{"type":"boolean"},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}}}},"effectivePermissions":{"type":"array","items":{"type":"string"}}},"required":["userId","tenantId","isSystemAdmin","isTenantAdmin","groups","effectivePermissions"]}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/iam/me/permissions":{"get":{"summary":"List effective permissions","tags":["System"],"description":"Retrieve the flattened list of effective permissions for the current user.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/iam/me/spaces":{"get":{"summary":"List user space memberships","tags":["System"],"description":"Retrieve the spaces the current user belongs to together with their membership roles.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"space_id":{"type":"string"},"space_name":{"type":"string"},"role":{"type":"string","enum":["manager","reader"]}},"required":["space_id","space_name","role"]}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/iam/me/spaces/manageable":{"get":{"summary":"List manageable spaces","tags":["System"],"description":"Retrieve the spaces the current user can manage as a tenant admin or space manager.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/iam/me/resources/manageable":{"get":{"summary":"List manageable resources","tags":["System"],"description":"Retrieve the resources the current user can manage via direct resource membership or manageable parent spaces.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"space_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","space_id","name"]}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/iam/can":{"get":{"summary":"Check entity permission","tags":["System"],"description":"Check whether the current user can perform a read or write action on a specific space or resource.","parameters":[{"schema":{"type":"string","enum":["space","resource"]},"in":"query","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"entityId","required":true},{"schema":{"type":"string","enum":["read","write"]},"in":"query","name":"action","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean"}},"required":["allowed"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/auth/identities":{"get":{"summary":"List linked identities","tags":["Auth"],"description":"Returns all OAuth providers linked to the current user account","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["google","microsoft","apple","facebook","github"]},"email":{"type":"string","format":"email","nullable":true},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatar_url":{"type":"string","format":"uri","nullable":true},"linked_at":{"type":"string","format":"date-time"},"last_login_at":{"type":"string","format":"date-time","nullable":true},"is_primary":{"type":"boolean","description":"Whether this is the primary login method"}},"required":["id","provider","displayName","fullName","linked_at"],"additionalProperties":false}},"email_auth_enabled":{"type":"boolean","description":"Whether email/password authentication is enabled for this user"},"total":{"type":"integer"}},"required":["data","email_auth_enabled","total"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/link/{provider}":{"post":{"summary":"Link OAuth provider","tags":["Auth"],"description":"Initiates OAuth flow to link a new provider to the current account","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"redirectUrl":{"type":"string","format":"uri","description":"URL to redirect to after OAuth linking completes"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","enum":["google","microsoft","apple","facebook","github"]},"in":"path","name":"provider","required":true,"description":"OAuth provider identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"OAuth authorization URL for linking"},"provider":{"type":"string","enum":["google","microsoft","apple","facebook","github"]}},"required":["url","provider"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/unlink/{provider}":{"delete":{"summary":"Unlink OAuth provider","tags":["Auth"],"description":"Removes a linked OAuth provider from the current account","parameters":[{"schema":{"type":"string","enum":["google","microsoft","apple","facebook","github"]},"in":"path","name":"provider","required":true,"description":"OAuth provider identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft","apple","facebook","github"]}},"required":["success","message","provider"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/primary/{provider}":{"patch":{"summary":"Set primary provider","tags":["Auth"],"description":"Sets the primary login method for the account","parameters":[{"schema":{"type":"string","enum":["google","microsoft","apple","facebook","github"]},"in":"path","name":"provider","required":true,"description":"OAuth provider identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"primary_provider":{"type":"string","enum":["google","microsoft","apple","facebook","github","email"]}},"required":["success","message","primary_provider"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/oauth-history":{"get":{"summary":"Get OAuth login history","tags":["Auth"],"description":"Returns recent OAuth login attempts for the current user","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string"},"success":{"type":"boolean"},"attempted_at":{"type":"string","format":"date-time"},"ip_address":{"type":"string","nullable":true}}}},"total":{"type":"integer"}},"required":["data","total"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/2fa/status":{"get":{"summary":"Get 2FA status","tags":["Auth"],"description":"Returns enabled 2FA methods and backup code count","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"enabled_methods":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string","enum":["totp","sms","email","whatsapp"]},"enabled_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true},"delivery_target_masked":{"type":"string","nullable":true}},"required":["method"]}},"backup_codes_remaining":{"type":"integer"},"requires_2fa":{"type":"boolean","description":"Whether tenant requires 2FA"}},"required":["enabled_methods","backup_codes_remaining","requires_2fa"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/2fa/enable/{method}":{"post":{"summary":"Enable 2FA method","tags":["Auth"],"description":"Initiates 2FA setup for the specified method","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_target":{"type":"string","description":"Phone number (SMS/WhatsApp) or email address (Email)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","enum":["totp","sms","email","whatsapp"]},"in":"path","name":"method","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"method":{"type":"string","enum":["totp"]},"secret":{"type":"string","description":"Base32 encoded secret (show to user once)"},"qr_code_uri":{"type":"string","description":"otpauth:// URI for QR code generation"},"qr_code_data_url":{"type":"string","description":"Data URL of QR code image"},"backup_codes":{"type":"array","items":{"type":"string"},"description":"One-time backup codes (10 codes)"}},"required":["method","secret","qr_code_uri","backup_codes"]}},"required":["success","message","data"],"additionalProperties":false},{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"method":{"type":"string","enum":["sms","email","whatsapp"]},"delivery_target":{"type":"string","description":"Masked phone/email"},"verification_sent":{"type":"boolean"},"expires_in_seconds":{"type":"integer","description":"Code expiration time"}},"required":["method","delivery_target","verification_sent"]}},"required":["success","message","data"],"additionalProperties":false}]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/2fa/verify":{"post":{"summary":"Verify 2FA code","tags":["Auth"],"description":"Verifies a 2FA code and enables the method if valid","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["totp","sms","email","whatsapp"]},"code":{"type":"string","minLength":6,"maxLength":8,"description":"6-8 digit verification code"}},"required":["method","code"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"method":{"type":"string","enum":["totp","sms","email","whatsapp"]},"verified":{"type":"boolean"},"enabled":{"type":"boolean"}},"required":["method","verified"]}},"required":["success","message","data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"429":{"description":"429 Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Error code for rate limit errors","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[429]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"429 Too Many Requests - Rate limit exceeded"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/2fa/disable":{"delete":{"summary":"Disable 2FA method","tags":["Auth"],"description":"Disables a 2FA method (requires current code or backup code)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["totp","sms","email","whatsapp"]},"code":{"type":"string","minLength":6,"maxLength":8,"description":"Current 2FA code to confirm disable"}},"required":["method","code"],"additionalProperties":false}}},"required":true},"responses":{"204":{"description":"2FA method disabled successfully"},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"429":{"description":"429 Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Error code for rate limit errors","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[429]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"429 Too Many Requests - Rate limit exceeded"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/2fa/send-code":{"post":{"summary":"Send verification code","tags":["Auth"],"description":"Sends a new verification code via the specified method","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["sms","email","whatsapp"],"description":"Delivery method for the code"}},"required":["method"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"sent":{"type":"boolean"},"expires_in_seconds":{"type":"integer"}}}},"required":["success","message","data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"429":{"description":"429 Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Error code for rate limit errors","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[429]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"429 Too Many Requests - Rate limit exceeded"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/2fa/backup-codes":{"post":{"summary":"Generate backup codes","tags":["Auth"],"description":"Generates new backup codes (invalidates any existing codes)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"backup_codes":{"type":"array","items":{"type":"string"},"description":"New backup codes (previous codes are invalidated)"},"count":{"type":"integer"}},"required":["backup_codes","count"]}},"required":["success","message","data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/2fa/use-backup":{"post":{"summary":"Use backup code","tags":["Auth"],"description":"Uses a one-time backup code for 2FA verification","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":8,"maxLength":12,"description":"One-time backup code"}},"required":["code"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"used":{"type":"boolean"},"remaining":{"type":"integer"}}}},"required":["success","message","data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"429":{"description":"429 Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Error code for rate limit errors","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[429]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"429 Too Many Requests - Rate limit exceeded"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/me":{"get":{"summary":"Get current user","tags":["Auth"],"description":"Get the current authenticated user profile, tenant context, groups, and permissions","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false},"description":"All tenant memberships linked to this user account"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local first name (e.g., Thai: สมชาย)"},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local middle name (optional)"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local last name (e.g., Thai: ใจดี)"},"displayName":{"type":"string","description":"Public display name. Never null; falls back to generated fullName."},"fullName":{"type":"string","description":"Generated full name using tenant-specific name ordering."},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Resolved avatar URL from selected source"},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"groupDetails":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"required":["id","name","permissions"],"additionalProperties":false}},"permissions":{"type":"array","items":{"type":"string"}},"isSystemAdmin":{"type":"boolean"},"isTenantAdmin":{"type":"boolean"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at","tenantName","groups","groupDetails","permissions","isSystemAdmin","isTenantAdmin"],"additionalProperties":false}},"required":["user"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"patch":{"summary":"Update current user","tags":["Auth"],"description":"Update the current authenticated user profile and typed settings payload","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"displayName":{"type":["string","null"]},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition ID or type name to validate the user settings payload"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false},"description":"All tenant memberships linked to this user account"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local first name (e.g., Thai: สมชาย)"},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local middle name (optional)"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local last name (e.g., Thai: ใจดี)"},"displayName":{"type":"string","description":"Public display name. Never null; falls back to generated fullName."},"fullName":{"type":"string","description":"Generated full name using tenant-specific name ordering."},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Resolved avatar URL from selected source"},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"groupDetails":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"required":["id","name","permissions"],"additionalProperties":false}},"permissions":{"type":"array","items":{"type":"string"}},"isSystemAdmin":{"type":"boolean"},"isTenantAdmin":{"type":"boolean"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at","tenantName","groups","groupDetails","permissions","isSystemAdmin","isTenantAdmin"],"additionalProperties":false}},"required":["user"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/me/change-password":{"post":{"summary":"Change current user password","tags":["Auth"],"description":"Verify the current password and update the current authenticated user password.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["currentPassword","newPassword"],"properties":{"currentPassword":{"type":"string","minLength":8},"newPassword":{"type":"string","minLength":8}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/me/preferences":{"delete":{"summary":"Reset current user settings","tags":["Auth"],"description":"Reset the current authenticated user typed settings payload to the system wildcard default","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantLinks":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false},"description":"All tenant memberships linked to this user account"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"],"description":"User lifecycle status"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local first name (e.g., Thai: สมชาย)"},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local middle name (optional)"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Native/local last name (e.g., Thai: ใจดี)"},"displayName":{"type":"string","description":"Public display name. Never null; falls back to generated fullName."},"fullName":{"type":"string","description":"Generated full name using tenant-specific name ordering."},"avatar_source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"},"avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Resolved avatar URL from selected source"},"profileImage":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Profile image from media service (main image for user)"},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Type definition controlling validation of the user settings payload"},"settings":{"type":"object","additionalProperties":true,"description":"Tenant-validated user-specific application settings and preferences"},"locale":{"type":"string","pattern":"^[a-z]{2}$","description":"User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."},"emailConfirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp from Supabase Auth when the user email was confirmed"},"emailVerificationStatus":{"type":"string","enum":["verified","pending","not_configured"],"description":"Current tenant confirmation-flow state for the user email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"groupDetails":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"required":["id","name","permissions"],"additionalProperties":false}},"permissions":{"type":"array","items":{"type":"string"}},"isSystemAdmin":{"type":"boolean"},"isTenantAdmin":{"type":"boolean"}},"required":["id","tenantId","tenantLinks","email","status","displayName","fullName","avatar_source","typeDefinitionId","settings","locale","emailConfirmedAt","emailVerificationStatus","created_at","updated_at","tenantName","groups","groupDetails","permissions","isSystemAdmin","isTenantAdmin"],"additionalProperties":false}},"required":["user"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/logout":{"post":{"summary":"Logout current user","tags":["Auth"],"description":"Invalidate the current authenticated session and clear the refresh token cookie","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/account":{"delete":{"summary":"Delete current account","tags":["Auth"],"description":"Retire the current PVE account, suspend tenant access, and soft-delete the backing auth user.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"accountClosedAt":{"type":"string","format":"date-time"}},"required":["success","message","accountClosedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/tenants":{"get":{"summary":"Get user tenants","tags":["Auth"],"description":"Returns list of tenants the current user has access to","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]},"status":{"type":"string","enum":["active","suspended","pending","invited"]},"is_default":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"}},"required":["user_id","tenantId","role","tenantName","tenantSlug"],"additionalProperties":false}},"activeTenantId":{"type":"string","format":"uuid","nullable":true},"defaultTenantId":{"type":"string","format":"uuid","nullable":true}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/switch-tenant":{"post":{"summary":"Switch tenant","tags":["Auth"],"description":"Switch the active tenant for the current session","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid","description":"Target tenant ID to switch to"}},"required":["tenantId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"tenantSlug":{"type":"string"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]}},"required":["success","tenantId","tenantName","tenantSlug","role"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/default-tenant":{"patch":{"summary":"Set default tenant","tags":["Auth"],"description":"Set the default tenant that will be used on login","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid","description":"Tenant ID to set as default"}},"required":["tenantId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"defaultTenantId":{"type":"string","format":"uuid"}},"required":["success","defaultTenantId"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/leave-tenant/{tenantId}":{"post":{"summary":"Leave tenant","tags":["Auth"],"description":"Remove yourself from a tenant membership","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"tenantId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/tenant-role":{"get":{"summary":"Get tenant role","tags":["Auth"],"description":"Get the current user's role in the active tenant","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","admin","manager","member","guest","system_admin"]}},"required":["tenantId","role"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/resolve-flow":{"post":{"summary":"Resolve auth flow","tags":["Auth"],"description":"Evaluate user state and return the next step after authentication","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["context"],"properties":{"context":{"type":"string","enum":["login","registration","verification","invitation"],"description":"The authentication context that triggered this resolve"}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["REDIRECT","PROCEED"]},"target":{"type":"string","description":"Route to redirect to, or dashboard if PROCEED"},"taskId":{"type":"string","format":"uuid","nullable":true},"pendingTasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["agb","profile","kyc","avatar","phone_verification","email_verification","custom"]},"name":{"type":"string"},"targetRoute":{"type":"string"},"isMandatory":{"type":"boolean"},"i18n":{"type":"object","additionalProperties":true}},"required":["id","type","name","targetRoute","isMandatory"]}}},"required":["action","target","pendingTasks"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/tasks/status":{"get":{"summary":"Get tasks status","tags":["Auth"],"description":"Get all tasks with completion status for the current user","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["agb","profile","kyc","avatar","phone_verification","email_verification","custom"]},"name":{"type":"string"},"targetRoute":{"type":"string"},"priority":{"type":"integer"},"isMandatory":{"type":"boolean"},"isCompleted":{"type":"boolean"},"completedAt":{"type":"string","format":"date-time","nullable":true},"completedVersion":{"type":"string","nullable":true},"currentVersion":{"type":"string","nullable":true},"requiresUpdate":{"type":"boolean","description":"True if AGB version changed"},"i18n":{"type":"object","additionalProperties":true}},"required":["id","type","name","targetRoute","priority","isMandatory","isCompleted"]}},"mandatoryCompleted":{"type":"integer"},"mandatoryTotal":{"type":"integer"},"optionalCompleted":{"type":"integer"},"optionalTotal":{"type":"integer"}},"required":["tasks","mandatoryCompleted","mandatoryTotal","optionalCompleted","optionalTotal"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/auth/tasks/{taskId}/complete":{"post":{"summary":"Complete task","tags":["Auth"],"description":"Mark a task as completed for the current user","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":true,"description":"Optional metadata for the task completion (e.g., AGB acceptance data)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"taskId":{"type":"string","format":"uuid"},"completedAt":{"type":"string","format":"date-time"},"nextAction":{"type":"string","enum":["REDIRECT","PROCEED"]},"nextTarget":{"type":"string"},"nextTaskId":{"type":"string","format":"uuid","nullable":true}},"required":["success","taskId","completedAt","nextAction","nextTarget"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/admin/flow-tasks/":{"get":{"summary":"List flow tasks","tags":["Admin"],"description":"Get all flow tasks configured for the tenant","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["agb","profile","kyc","avatar","phone_verification","email_verification","custom"]},"name":{"type":"string"},"targetRoute":{"type":"string"},"priority":{"type":"integer"},"isMandatory":{"type":"boolean"},"isActive":{"type":"boolean"},"version":{"type":"string","nullable":true},"config":{"type":"object","additionalProperties":true},"i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"buttonText":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","type","name","targetRoute","priority","isMandatory","isActive"],"additionalProperties":false}},"total":{"type":"integer"}},"required":["data","total"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"post":{"summary":"Create flow task","tags":["Admin"],"description":"Create a new flow task for the tenant","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","name","targetRoute"],"properties":{"type":{"type":"string","enum":["agb","profile","kyc","avatar","phone_verification","email_verification","custom"]},"name":{"type":"string","minLength":1,"maxLength":100},"targetRoute":{"type":"string","minLength":1,"maxLength":255},"priority":{"type":"integer","minimum":0,"default":0},"isMandatory":{"type":"boolean","default":false},"isActive":{"type":"boolean","default":true},"version":{"type":"string","maxLength":50,"nullable":true},"config":{"type":"object","additionalProperties":true},"i18n":{"type":"object","additionalProperties":true}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["agb","profile","kyc","avatar","phone_verification","email_verification","custom"]},"name":{"type":"string"},"targetRoute":{"type":"string"},"priority":{"type":"integer"},"isMandatory":{"type":"boolean"},"isActive":{"type":"boolean"},"version":{"type":"string","nullable":true},"config":{"type":"object","additionalProperties":true},"i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"buttonText":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","type","name","targetRoute","priority","isMandatory","isActive"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/admin/flow-tasks/{id}":{"patch":{"summary":"Update flow task","tags":["Admin"],"description":"Update an existing flow task","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"targetRoute":{"type":"string","minLength":1,"maxLength":255},"priority":{"type":"integer","minimum":0},"isMandatory":{"type":"boolean"},"isActive":{"type":"boolean"},"version":{"type":"string","maxLength":50,"nullable":true},"config":{"type":"object","additionalProperties":true},"i18n":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["agb","profile","kyc","avatar","phone_verification","email_verification","custom"]},"name":{"type":"string"},"targetRoute":{"type":"string"},"priority":{"type":"integer"},"isMandatory":{"type":"boolean"},"isActive":{"type":"boolean"},"version":{"type":"string","nullable":true},"config":{"type":"object","additionalProperties":true},"i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"buttonText":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","type","name","targetRoute","priority","isMandatory","isActive"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Delete flow task","tags":["Admin"],"description":"Delete a flow task from the tenant","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/admin/flow-tasks/{id}/reset":{"post":{"summary":"Reset task for all users","tags":["Admin"],"description":"Reset a task completion for all users (e.g., when AGB version changes)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"resetCount":{"type":"integer"}},"required":["success","resetCount"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/admin/flow-tasks/reorder":{"patch":{"summary":"Reorder flow tasks","tags":["Admin"],"description":"Reorder tasks by providing task IDs in the desired priority order","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["taskIds"],"properties":{"taskIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"description":"Task IDs in the desired priority order (first = highest priority)"}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/profile/avatar/sources":{"get":{"summary":"Get available avatar sources","tags":["Profile"],"description":"Returns all available avatar sources including generated, uploaded, and OAuth provider avatars","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"currentSource":{"type":"string","enum":["none","uploaded","remote"],"description":"Currently selected avatar source"},"currentIdentityId":{"type":"string","format":"uuid","nullable":true,"description":"Identity ID if current source is remote"},"currentAvatarUrl":{"type":"string","format":"uri","nullable":true,"description":"Current resolved avatar URL ready for direct rendering; may be a signed media URL or remote provider URL"},"availableSources":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source type"},"previewUrl":{"type":"string","format":"uri","description":"Preview URL for this avatar source"},"thumbnailUrl":{"type":"string","format":"uri","nullable":true,"description":"Thumbnail URL (for uploaded avatars)"},"identityId":{"type":"string","format":"uuid","nullable":true,"description":"Identity ID (for remote avatars)"},"provider":{"type":"string","enum":["google","microsoft","apple","facebook","github"],"nullable":true,"description":"OAuth provider (for remote avatars)"},"providerName":{"type":"string","nullable":true,"description":"Display name of the OAuth provider"}},"required":["type","previewUrl"],"additionalProperties":false},"description":"All available avatar sources for this user"}},"required":["currentSource","availableSources"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/profile/avatar/":{"patch":{"summary":"Set avatar source","tags":["Profile"],"description":"Sets the avatar source for the current user profile","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["none","uploaded","remote"],"description":"Avatar source to set"},"identityId":{"type":"string","format":"uuid","nullable":true,"description":"Identity ID (required when source is \"remote\")"}},"required":["source"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"source":{"type":"string","enum":["none","uploaded","remote"]},"avatarUrl":{"type":"string","format":"uri","nullable":true},"identityId":{"type":"string","format":"uuid","nullable":true}},"required":["source"]}},"required":["success","message","data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Reset avatar","tags":["Profile"],"description":"Resets the avatar to generated mode (initials-based)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"source":{"type":"string","enum":["none"]},"avatarUrl":{"type":"string","format":"uri","description":"Generated avatar URL"}},"required":["source","avatarUrl"]}},"required":["success","message","data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"get":{"summary":"Get current avatar","tags":["Profile"],"description":"Returns the current avatar source and resolved direct-render URL for the user","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"source":{"type":"string","enum":["none","uploaded","remote"],"description":"Currently active avatar source"},"avatarUrl":{"type":"string","format":"uri","nullable":true,"description":"Resolved avatar URL ready for direct rendering; may be a signed media URL or remote provider URL"},"identityId":{"type":"string","format":"uuid","nullable":true,"description":"Identity ID when the active source is remote"}},"required":["source"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/tenant/approval-settings":{"get":{"summary":"Get approval settings","tags":["Approval"],"description":"Get approval settings for all entity types","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string","enum":["space","resource","calendar_entry"]},"requires_approval":{"type":"boolean"},"config":{"type":"object","properties":{"auto_approve_roles":{"type":"array","items":{"type":"string"},"description":"Roles that can auto-approve entities (default: owner, admin)","default":["owner","admin"]},"max_pending_days":{"type":"number","description":"Maximum days an approval can be pending before expiring","default":30,"minimum":1,"maximum":365},"notify_admins":{"type":"boolean","description":"Whether to notify admins when a new approval request is created","default":true},"notify_creator_on_decision":{"type":"boolean","description":"Whether to notify the creator when the request is approved/rejected","default":true}}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/tenant/approval-settings/{entityType}":{"patch":{"summary":"Update approval settings","tags":["Approval"],"description":"Update approval settings for an entity type (admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"requires_approval":{"type":"boolean"},"config":{"type":"object","properties":{"auto_approve_roles":{"type":"array","items":{"type":"string"}},"max_pending_days":{"type":"number","minimum":1,"maximum":365},"notify_admins":{"type":"boolean"},"notify_creator_on_decision":{"type":"boolean"}}}}}}}},"parameters":[{"schema":{"type":"string","enum":["space","resource","calendar_entry"]},"in":"path","name":"entityType","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"entity_type":{"type":"string","enum":["space","resource","calendar_entry"]},"requires_approval":{"type":"boolean"},"config":{"type":"object","properties":{"auto_approve_roles":{"type":"array","items":{"type":"string"},"description":"Roles that can auto-approve entities (default: owner, admin)","default":["owner","admin"]},"max_pending_days":{"type":"number","description":"Maximum days an approval can be pending before expiring","default":30,"minimum":1,"maximum":365},"notify_admins":{"type":"boolean","description":"Whether to notify admins when a new approval request is created","default":true},"notify_creator_on_decision":{"type":"boolean","description":"Whether to notify the creator when the request is approved/rejected","default":true}}}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/approvals":{"get":{"summary":"List approval requests","tags":["Approval"],"description":"List approval requests","parameters":[{"schema":{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["space","resource","calendar_entry"]},"in":"query","name":"entity_type","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"created_by","required":false},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data","total","limit","offset"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","calendar_entry"]},"entity_id":{"type":"string","format":"uuid"},"entity_name":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},"reason":{"type":"string"},"decision_at":{"type":"string","format":"date-time"},"decision_by":{"type":"string","format":"uuid"},"rejection_reason":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"creator":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"}},"required":["id","email","displayName","fullName"]},"decider":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"}},"required":["id","email","displayName","fullName"]}}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/approvals/{id}":{"get":{"summary":"Get approval request","tags":["Approval"],"description":"Get an approval request by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","calendar_entry"]},"entity_id":{"type":"string","format":"uuid"},"entity_name":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},"reason":{"type":"string"},"decision_at":{"type":"string","format":"date-time"},"decision_by":{"type":"string","format":"uuid"},"rejection_reason":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"creator":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"}},"required":["id","email","displayName","fullName"]},"decider":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"fullName":{"type":"string"}},"required":["id","email","displayName","fullName"]}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Cancel request","tags":["Approval"],"description":"Cancel a pending approval request (creator or admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Request cancelled successfully"},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/approvals/{id}/approve":{"post":{"summary":"Approve request","tags":["Approval"],"description":"Approve a pending approval request (admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"string","maxLength":500}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data","message"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","calendar_entry"]},"entity_id":{"type":"string","format":"uuid"},"entity_name":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},"reason":{"type":"string"},"decision_at":{"type":"string","format":"date-time"},"decision_by":{"type":"string","format":"uuid"},"rejection_reason":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"message":{"type":"string"}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/approvals/{id}/reject":{"post":{"summary":"Reject request","tags":["Approval"],"description":"Reject a pending approval request (admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["rejection_reason"],"properties":{"rejection_reason":{"type":"string","minLength":1,"maxLength":500}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data","message"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","calendar_entry"]},"entity_id":{"type":"string","format":"uuid"},"entity_name":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},"reason":{"type":"string"},"decision_at":{"type":"string","format":"date-time"},"decision_by":{"type":"string","format":"uuid"},"rejection_reason":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"message":{"type":"string"}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/me/approvals":{"get":{"summary":"Get my approval requests","tags":["Approval"],"description":"Get current user's approval requests","parameters":[{"schema":{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data","total"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","calendar_entry"]},"entity_id":{"type":"string","format":"uuid"},"entity_name":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},"reason":{"type":"string"},"decision_at":{"type":"string","format":"date-time"},"decision_by":{"type":"string","format":"uuid"},"rejection_reason":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"total":{"type":"number"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/spaces/":{"get":{"summary":"List spaces","tags":["Spaces"],"description":"Retrieve paginated spaces with optional filtering by type, status, taxonomy, manageability, and location.","parameters":[{"schema":{"type":"string","enum":["system","default","custom"]},"in":"query","name":"type","required":false,"description":"Filter by space type"},{"schema":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"in":"query","name":"status","required":false,"description":"Filter by space status"},{"schema":{"type":"string"},"in":"query","name":"type_name","required":false,"description":"Filter by space type name"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"type_definition_id","required":false,"description":"Filter by type definition ID"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search query for name/description"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"tag_ids","required":false,"description":"Filter by tag IDs"},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"tag_names","required":false,"description":"Filter by tag names"},{"schema":{"type":"boolean"},"in":"query","name":"match_all_tags","required":false,"description":"Match all tag filters instead of any tag"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"category_ids","required":false,"description":"Filter by category IDs"},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"category_keys","required":false,"description":"Filter by category keys"},{"schema":{"type":"boolean"},"in":"query","name":"match_all_categories","required":false,"description":"Match all category filters instead of any category"},{"schema":{"type":"boolean"},"in":"query","name":"include_children","required":false,"description":"Include hierarchical category children when category keys are used"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_after","required":false,"description":"Filter by created_at >="},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_before","required":false,"description":"Filter by created_at <="},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_after","required":false,"description":"Filter by updated_at >="},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_before","required":false,"description":"Filter by updated_at <="},{"schema":{"type":"boolean"},"in":"query","name":"manageable","required":false,"description":"If true, only return spaces user can manage"},{"schema":{"type":"boolean"},"in":"query","name":"include_metrics","required":false,"description":"If true, include opt-in visit metric summary fields for the current page of spaces"},{"schema":{"type":"boolean"},"in":"query","name":"subscription_active","required":false,"description":"Filter by computed subscription activity state"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"subscription_check_timestamp","required":false,"description":"Evaluate subscription activity at this timestamp; defaults to current server time"},{"schema":{"type":"string"},"in":"query","name":"sort_by","required":false,"description":"Sort field, including distance"},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"sort_direction","required":false,"description":"Sort direction"},{"schema":{"type":"number","minimum":-90,"maximum":90},"in":"query","name":"reference_latitude","required":false,"description":"Reference latitude for distance sorting or geo radius filtering"},{"schema":{"type":"number","minimum":-180,"maximum":180},"in":"query","name":"reference_longitude","required":false,"description":"Reference longitude for distance sorting or geo radius filtering"},{"schema":{"type":"integer","minimum":1},"in":"query","name":"radius_meters","required":false,"description":"Geo radius filter in meters around the reference coordinates"},{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"preferredLanguage","required":false,"description":"ISO 639-1 language code for localized results"},{"schema":{"type":"number","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset","required":false,"description":"Pagination offset"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description"},"type":{"type":"string","enum":["system","default","custom"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"manageable":{"type":"boolean","description":"Whether current user can manage this space"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this space."},"subscription":{"type":"boolean","description":"Whether this space is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"description":"Translations for additional languages (excludes base language)"},"distanceMeters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this space. Use media entity endpoints for the full media collection."}},"required":["id","tenantId","name","type","typeName","typeDefinitionId","status","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive","distanceMeters","mainMedia"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"tags":["Spaces"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":255,"description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$","description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"type":{"type":"string","enum":["system","default","custom"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"settings":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"subscriptionTypeId":{"anyOf":[{"type":"integer","minimum":0,"description":"Subscription type identifier for this space."},{"type":"null"}]},"subscription":{"anyOf":[{"type":"boolean","description":"Whether this space is currently managed as a subscription item."},{"type":"null"}]},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"homeLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}]},"category_ids":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}]},"tag_ids":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}]},"translations_i18n":{"anyOf":[{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]}},{"type":"null"}],"description":"Translations for additional languages (excludes base language)"}},"required":["name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"type":{"type":"string","enum":["system","default","custom"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"manageable":{"type":"boolean","description":"Whether current user can manage this space"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this space."},"subscription":{"type":"boolean","description":"Whether this space is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Space-specific settings and metadata"},"distanceMeters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"},"homeLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of the space home location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this space. Use media entity endpoints for the full media collection."}},"required":["id","tenantId","name","type","typeName","typeDefinitionId","status","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive","distanceMeters"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}":{"get":{"summary":"Get space details","tags":["Spaces"],"description":"Retrieve a specific space with localized fields, optional distance context, and visit metrics enrichment.","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"preferredLanguage","required":false,"description":"ISO 639-1 language code for localized response"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"subscription_check_timestamp","required":false,"description":"Evaluate subscription activity at this timestamp; defaults to current server time"},{"schema":{"type":"number","minimum":-90,"maximum":90},"in":"query","name":"reference_latitude","required":false,"description":"Reference latitude for computed distance display"},{"schema":{"type":"number","minimum":-180,"maximum":180},"in":"query","name":"reference_longitude","required":false,"description":"Reference longitude for computed distance display"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"type":{"type":"string","enum":["system","default","custom"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"manageable":{"type":"boolean","description":"Whether current user can manage this space"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this space."},"subscription":{"type":"boolean","description":"Whether this space is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Space-specific settings and metadata"},"distanceMeters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"},"homeLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of the space home location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this space. Use media entity endpoints for the full media collection."}},"required":["id","tenantId","name","type","typeName","typeDefinitionId","status","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive","distanceMeters"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"tags":["Spaces"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":255,"description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$","description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"type":{"type":"string","enum":["system","default","custom"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"settings":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"subscriptionTypeId":{"anyOf":[{"type":"integer","minimum":0,"description":"Subscription type identifier for this space."},{"type":"null"}]},"subscription":{"anyOf":[{"type":"boolean","description":"Whether this space is currently managed as a subscription item."},{"type":"null"}]},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"homeLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}]},"category_ids":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}]},"tag_ids":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}]},"translations_i18n":{"anyOf":[{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]}},{"type":"null"}],"description":"Translations for additional languages (excludes base language)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"type":{"type":"string","enum":["system","default","custom"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"manageable":{"type":"boolean","description":"Whether current user can manage this space"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this space."},"subscription":{"type":"boolean","description":"Whether this space is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Space-specific settings and metadata"},"distanceMeters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"},"homeLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of the space home location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this space. Use media entity endpoints for the full media collection."}},"required":["id","tenantId","name","type","typeName","typeDefinitionId","status","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive","distanceMeters"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"tags":["Spaces"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/visit-metrics/track":{"post":{"summary":"Track space detail visit","tags":["Spaces"],"description":"Records a space detail visit explicitly. Call this asynchronously after the space record is displayed to the user. Use GET /api/v1/secure/spaces/{id} for the current summary fields and POST this endpoint only when the app decides the view counts as a visit.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entityId":{"type":"string","format":"uuid"},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"lastVisitedByActorType":{"anyOf":[{"type":"string","enum":["user","api_key","app_account"]},{"type":"null"}]},"lastVisitedByActorId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastResetAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastResetByActorType":{"anyOf":[{"type":"string","enum":["user","api_key","app_account"]},{"type":"null"}]},"lastResetByActorId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastResetReason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["entityId","totalVisits","lastVisitedAt","lastVisitedByActorType","lastVisitedByActorId","lastResetAt","lastResetByActorType","lastResetByActorId","lastResetReason"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/visit-metrics/reset":{"post":{"summary":"Reset space visit metrics","tags":["Spaces"],"description":"Resets the aggregated visit metrics counters for a single space.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entityId":{"type":"string","format":"uuid"},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"lastVisitedByActorType":{"anyOf":[{"type":"string","enum":["user","api_key","app_account"]},{"type":"null"}]},"lastVisitedByActorId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastResetAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastResetByActorType":{"anyOf":[{"type":"string","enum":["user","api_key","app_account"]},{"type":"null"}]},"lastResetByActorId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastResetReason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["entityId","totalVisits","lastVisitedAt","lastVisitedByActorType","lastVisitedByActorId","lastResetAt","lastResetByActorType","lastResetByActorId","lastResetReason"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/order-top":{"post":{"summary":"Move space to top order","tags":["Spaces"],"description":"Assigns the next highest custom order value to the space so it appears at the top of space list and nearby results.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"type":{"type":"string","enum":["system","default","custom"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"manageable":{"type":"boolean","description":"Whether current user can manage this space"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this space."},"subscription":{"type":"boolean","description":"Whether this space is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Space-specific settings and metadata"},"distanceMeters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"},"homeLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of the space home location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this space. Use media entity endpoints for the full media collection."}},"required":["id","tenantId","name","type","typeName","typeDefinitionId","status","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive","distanceMeters"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/promotion":{"patch":{"summary":"Update space promotion","tags":["Spaces"],"description":"Assign, update, or clear the promotion rank and active window for a space.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"type":{"type":"string","enum":["system","default","custom"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"manageable":{"type":"boolean","description":"Whether current user can manage this space"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this space; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this space."},"subscription":{"type":"boolean","description":"Whether this space is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Space-specific settings and metadata"},"distanceMeters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"},"homeLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of the space home location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this space. Use media entity endpoints for the full media collection."}},"required":["id","tenantId","name","type","typeName","typeDefinitionId","status","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive","distanceMeters"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/members":{"get":{"summary":"List space members","tags":["Space Members"],"description":"Retrieve all members assigned to a specific space and their current roles.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"space_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["manager","reader"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","space_id","user_id","role","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"tags":["Space Members"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["manager","reader"]}},"required":["userId","role"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"space_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["manager","reader"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","space_id","user_id","role","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/members/{userId}":{"delete":{"tags":["Space Members"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"userId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/tags":{"get":{"summary":"List space tags","tags":["Spaces"],"description":"Get all tags linked to a space","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"preferredLanguage","required":false,"description":"ISO 639-1 language code for localized responses"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Localized display name (preferred language with base-language fallback)"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Localized category summaries linked to the tag"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"returnedCount":{"type":"number"},"total":{"type":"number"}},"required":["data","returnedCount"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Link space tag","tags":["Spaces"],"description":"Link a tag to a space (creates tag if it doesn't exist)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tag_name":{"type":"string","minLength":1,"maxLength":100}},"required":["tag_name"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tag_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tag_id","entity_type","entity_id","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/tags/{tagId}":{"delete":{"summary":"Unlink space tag","tags":["Spaces"],"description":"Unlink a tag from a space","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"tagId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/categories":{"get":{"summary":"List space categories","tags":["Spaces"],"description":"Get all categories linked to a space","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"preferredLanguage","required":false,"description":"ISO 639-1 language code for localized responses"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"level":{"type":"number"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string","description":"Localized name (preferred language with EN fallback)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Localized description"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code"},"usage_count":{"type":"number"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","usage_count","created_at","updated_at"],"additionalProperties":false}},"returnedCount":{"type":"number"},"total":{"type":"number"}},"required":["data","returnedCount"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Link space category","tags":["Spaces"],"description":"Link a category to a space","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"}},"required":["category_id"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"categoryId":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["space","resource","tenant","group"]},"entityId":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","categoryId","entityType","entityId","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/categories/{categoryId}":{"delete":{"summary":"Unlink space category","tags":["Spaces"],"description":"Unlink a category from a space","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"categoryId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/export":{"get":{"summary":"Export spaces","tags":["Spaces"],"description":"Export spaces to Excel/CSV/TSV","parameters":[{"schema":{"type":"string","enum":["xlsx","csv","tsv","json","json-schema"],"default":"xlsx"},"in":"query","name":"format","required":false,"description":"Export file format (xlsx, csv, tsv)"},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeExample","required":false,"description":"Include example row if data is empty"},{"schema":{"type":"number","minimum":1,"maximum":10000,"default":10000},"in":"query","name":"limit","required":false,"description":"Maximum number of rows to export"},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Offset for pagination"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Binary file download","content":{"application/json":{"schema":{"description":"Binary file download","type":"string","format":"binary"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/spaces/import":{"post":{"summary":"Import spaces","tags":["Spaces"],"description":"Import spaces from Excel/CSV/TSV file","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether import completed without critical errors"},"dryRun":{"type":"boolean","description":"Whether this was a validation-only dry run"},"entityType":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"],"description":"Entity type that was imported"},"stats":{"type":"object","properties":{"created":{"type":"number","description":"Number of entities created"},"updated":{"type":"number","description":"Number of entities updated"},"skipped":{"type":"number","description":"Number of entities skipped (merge strategy)"},"duplicates":{"type":"number","description":"Number of duplicate entries detected"},"errors":{"type":"number","description":"Number of rows with errors"}},"required":["created","updated","skipped","duplicates","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","description":"Row number (1-based, including header)"},"column":{"type":"string","description":"Column name where error occurred"},"value":{"type":"string","description":"Value that caused the error"},"identifier":{"type":"string","description":"Entity identifier (name, key, id)"},"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["INVALID_FORMAT","REQUIRED_FIELD","INVALID_UUID","DUPLICATE_ENTRY","REFERENCE_NOT_FOUND","VALIDATION_ERROR","IMPORT_ERROR","FILE_ERROR"]}},"required":["identifier","message","code"],"additionalProperties":false},"description":"Detailed error information per row"},"processedRows":{"type":"number","description":"Total number of rows processed"},"totalRows":{"type":"number","description":"Total number of rows in file"}},"required":["success","dryRun","entityType","stats","warnings","errors"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/resources/":{"get":{"summary":"List resources","tags":["Resources"],"description":"List all resources in tenant with filtering and pagination","parameters":[{"schema":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"in":"query","name":"status","required":false,"description":"Filter by resource status"},{"schema":{"type":"string"},"in":"query","name":"type_name","required":false,"description":"Filter by resource type name"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"type_definition_id","required":false,"description":"Filter by type definition ID"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"space_ids","required":false,"description":"Filter by space IDs"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search query for name/description"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"tag_ids","required":false,"description":"Filter by tag IDs"},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"tag_names","required":false,"description":"Filter by tag names"},{"schema":{"type":"boolean"},"in":"query","name":"match_all_tags","required":false,"description":"Match all tag filters instead of any tag"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"category_ids","required":false,"description":"Filter by category IDs"},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"category_keys","required":false,"description":"Filter by category keys"},{"schema":{"type":"boolean"},"in":"query","name":"match_all_categories","required":false,"description":"Match all category filters instead of any category"},{"schema":{"type":"boolean"},"in":"query","name":"include_children","required":false,"description":"Include hierarchical category children"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_after","required":false,"description":"Filter by created_at >="},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_before","required":false,"description":"Filter by created_at <="},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_after","required":false,"description":"Filter by updated_at >="},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_before","required":false,"description":"Filter by updated_at <="},{"schema":{"type":"boolean"},"in":"query","name":"manageable","required":false,"description":"If true, only return resources user can manage"},{"schema":{"type":"boolean"},"in":"query","name":"include_metrics","required":false,"description":"If true, include opt-in visit metric summary fields for the current page of resources"},{"schema":{"type":"boolean"},"in":"query","name":"subscription_active","required":false,"description":"Filter by computed subscription activity state"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"subscription_check_timestamp","required":false,"description":"Evaluate subscription activity at this timestamp; defaults to current server time"},{"schema":{"type":"string"},"in":"query","name":"sort_by","required":false,"description":"Sort field for generic resource list ordering"},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"sort_direction","required":false,"description":"Sort direction"},{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"preferredLanguage","required":false,"description":"ISO 639-1 language code for localized results"},{"schema":{"type":"number","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset","required":false,"description":"Pagination offset"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["system","custom"]},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"Translations for additional languages (excludes base language)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"manageable":{"type":"boolean","description":"Whether current user can manage this resource"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},"subscription":{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"space_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"current_space_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the current space (resolved)"},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this resource. Use media entity endpoints for the full media collection."}},"required":["id","type","name","language","translations_i18n","status","typeName","typeDefinitionId","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive","currentLocation","mainMedia"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"tags":["Resources"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$","description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"settings":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"subscriptionTypeId":{"anyOf":[{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},{"type":"null"}]},"subscription":{"anyOf":[{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},{"type":"null"}]},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"categoryIds":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}],"description":"Category IDs to link to this resource during create."},"tagIds":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}],"description":"Tag IDs to link to this resource during create."},"translationsI18n":{"anyOf":[{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]}},{"type":"null"}],"description":"Translations for additional languages (excludes base language)"}},"required":["name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["system","custom"]},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"manageable":{"type":"boolean","description":"Whether current user can manage this resource"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},"subscription":{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"space_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"current_space_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the current space (resolved)"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Resource-specific settings and metadata"},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this resource. Use media entity endpoints for the full media collection."}},"required":["id","type","name","status","typeName","typeDefinitionId","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/nearby":{"get":{"summary":"Search nearby resources","tags":["Resources"],"description":"Use this route for GPS, GIS, geo, geolocation, and near-me resource discovery with PostGIS-native filtering, distance ordering, and page-scoped enrichment.","parameters":[{"schema":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"in":"query","name":"status","required":false,"description":"Filter by resource status"},{"schema":{"type":"string"},"in":"query","name":"type_name","required":false,"description":"Filter by resource type name"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"type_definition_id","required":false,"description":"Filter by type definition ID"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"space_ids","required":false,"description":"Filter by space IDs"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search query for name/description"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"tag_ids","required":false,"description":"Filter by tag IDs"},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"tag_names","required":false,"description":"Filter by tag names"},{"schema":{"type":"boolean"},"in":"query","name":"match_all_tags","required":false,"description":"Match all tag filters instead of any tag"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"category_ids","required":false,"description":"Filter by category IDs"},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"category_keys","required":false,"description":"Filter by category keys"},{"schema":{"type":"boolean"},"in":"query","name":"match_all_categories","required":false,"description":"Match all category filters instead of any category"},{"schema":{"type":"boolean"},"in":"query","name":"include_children","required":false,"description":"Include hierarchical category children when category keys are used"},{"schema":{"type":"boolean"},"in":"query","name":"manageable","required":false,"description":"If true, only return resources user can manage"},{"schema":{"type":"boolean"},"in":"query","name":"subscription_active","required":false,"description":"Filter by computed subscription activity state"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"subscription_check_timestamp","required":false,"description":"Evaluate subscription activity at this timestamp; defaults to current server time"},{"schema":{"type":"number","minimum":-90,"maximum":90},"in":"query","name":"reference_latitude","required":true,"description":"Reference latitude for nearby search"},{"schema":{"type":"number","minimum":-180,"maximum":180},"in":"query","name":"reference_longitude","required":true,"description":"Reference longitude for nearby search"},{"schema":{"type":"integer","minimum":1},"in":"query","name":"radius_meters","required":false,"description":"Optional radius filter in meters around the reference coordinates"},{"schema":{"type":"boolean"},"in":"query","name":"include_media_ids","required":false,"description":"Include linked media ids for each nearby resource result"},{"schema":{"type":"string"},"in":"query","name":"sort_by","required":false,"description":"Nearby sort field. Supports distance, custom_order, created_at, updated_at, or name"},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"sort_direction","required":false,"description":"Nearby sort direction for the selected sort field"},{"schema":{"type":"number","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset","required":false,"description":"Pagination offset"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["system","custom"]},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"Translations for additional languages (excludes base language)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"manageable":{"type":"boolean","description":"Whether current user can manage this resource"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},"subscription":{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"space_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"current_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"distanceMeters":{"type":"number","description":"Distance from the supplied reference coordinates in meters"},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"mediaFileIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Linked media file ids for the nearby result page when requested; empty when omitted."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"settings":{"type":"object","additionalProperties":true,"description":"Resource-specific settings and metadata (includes type-definition fields such as country, price1hAmount, price1hCurrency)"},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this resource. Use media entity endpoints for the full media collection."}},"required":["id","type","name","language","translations_i18n","status","typeDefinitionId","typeName","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive","space_id","current_space_name","distanceMeters","currentLocation","categories","tags","mediaFileIds","created_at","updated_at","settings","mainMedia"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}":{"get":{"summary":"Get resource details","tags":["Resources"],"description":"Retrieve a specific resource with localized fields, current location metadata, and the current visit metric summary fields. The response can include totalVisits and lastVisitedAt when entity visit metrics are enabled, but it does not increment the counter. Clients should call POST /api/v1/secure/resources/{id}/visit-metrics/track asynchronously after the record is actually displayed to the user.","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"preferredLanguage","required":false,"description":"ISO 639-1 language code for localized response"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"subscription_check_timestamp","required":false,"description":"Evaluate subscription activity at this timestamp; defaults to current server time"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["system","custom"]},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"manageable":{"type":"boolean","description":"Whether current user can manage this resource"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},"subscription":{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"space_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"current_space_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the current space (resolved)"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Resource-specific settings and metadata"},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this resource. Use media entity endpoints for the full media collection."}},"required":["id","type","name","status","typeName","typeDefinitionId","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update resource","tags":["Resources"],"description":"Update a resource and return the enriched resource payload. When tagIds or categoryIds are provided, the resource taxonomy links are replaced to match the provided IDs.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$","description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"settings":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"subscriptionTypeId":{"anyOf":[{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},{"type":"null"}]},"subscription":{"anyOf":[{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},{"type":"null"}]},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"categoryIds":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}],"description":"When provided, replaces all category links on the resource with this exact set."},"tagIds":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}],"description":"When provided, replaces all tag links on the resource with this exact set."},"translationsI18n":{"anyOf":[{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]}},{"type":"null"}],"description":"Translations for additional languages (excludes base language)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["system","custom"]},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"manageable":{"type":"boolean","description":"Whether current user can manage this resource"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},"subscription":{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"space_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"current_space_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the current space (resolved)"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Resource-specific settings and metadata"},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this resource. Use media entity endpoints for the full media collection."}},"required":["id","type","name","status","typeName","typeDefinitionId","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"tags":["Resources"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/visit-metrics/track":{"post":{"summary":"Track resource detail visit","tags":["Resources"],"description":"Records a resource detail visit explicitly. Call this asynchronously after the resource record is displayed to the user. Use GET /api/v1/secure/resources/{id} for the current summary fields and POST this endpoint only when the app decides the view counts as a visit.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entityId":{"type":"string","format":"uuid"},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"lastVisitedByActorType":{"anyOf":[{"type":"string","enum":["user","api_key","app_account"]},{"type":"null"}]},"lastVisitedByActorId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastResetAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastResetByActorType":{"anyOf":[{"type":"string","enum":["user","api_key","app_account"]},{"type":"null"}]},"lastResetByActorId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastResetReason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["entityId","totalVisits","lastVisitedAt","lastVisitedByActorType","lastVisitedByActorId","lastResetAt","lastResetByActorType","lastResetByActorId","lastResetReason"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/visit-metrics/reset":{"post":{"summary":"Reset resource visit metrics","tags":["Resources"],"description":"Resets the aggregated visit metrics counters for a single resource.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entityId":{"type":"string","format":"uuid"},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"lastVisitedByActorType":{"anyOf":[{"type":"string","enum":["user","api_key","app_account"]},{"type":"null"}]},"lastVisitedByActorId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastResetAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastResetByActorType":{"anyOf":[{"type":"string","enum":["user","api_key","app_account"]},{"type":"null"}]},"lastResetByActorId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastResetReason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["entityId","totalVisits","lastVisitedAt","lastVisitedByActorType","lastVisitedByActorId","lastResetAt","lastResetByActorType","lastResetByActorId","lastResetReason"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/order-top":{"post":{"summary":"Move resource to top order","tags":["Resources"],"description":"Assigns the next highest custom order value to the resource so it appears at the top of resource list and nearby results.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["system","custom"]},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"manageable":{"type":"boolean","description":"Whether current user can manage this resource"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},"subscription":{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"space_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"current_space_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the current space (resolved)"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Resource-specific settings and metadata"},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this resource. Use media entity endpoints for the full media collection."}},"required":["id","type","name","status","typeName","typeDefinitionId","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/promotion":{"patch":{"summary":"Update resource promotion","tags":["Resources"],"description":"Assign, update, or clear the promotion rank and active window for a resource.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["system","custom"]},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"manageable":{"type":"boolean","description":"Whether current user can manage this resource"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},"subscription":{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"space_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"current_space_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the current space (resolved)"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Resource-specific settings and metadata"},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this resource. Use media entity endpoints for the full media collection."}},"required":["id","type","name","status","typeName","typeDefinitionId","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/detach":{"post":{"tags":["Resources"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["system","custom"]},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"},"status":{"type":"string","enum":["active","inactive","maintenance","retired","pending"]},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"typeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"manageable":{"type":"boolean","description":"Whether current user can manage this resource"},"promotionType":{"type":"string","enum":["None","Effect1","Effect2","Effect3","CommercialAdd"],"default":"None","description":"Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."},"promotionPlacement":{"type":"string","enum":["none","positionFix","positionDynamic","categoryPin","geoBoost"],"default":"none","description":"Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."},"promotionBadge":{"type":"string","enum":["none","featured","verifiedPro","fastReply"],"default":"none","description":"Promotion badge shown in UI contexts."},"promotionRank":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Purchased absolute list rank for this resource; null when not promoted"},"promotionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion start date; null means active immediately"},"promotionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Promotion end date; null means promotion does not expire"},"customOrder":{"type":"integer","minimum":1,"description":"Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."},"subscriptionTypeId":{"type":"integer","minimum":0,"description":"Subscription type identifier for this resource."},"subscription":{"type":"boolean","description":"Whether this resource is currently managed as a subscription item."},"subscriptionStartDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription start date; null means not scheduled"},"subscriptionEndDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Subscription end date; null means no end date is scheduled"},"subscriptionActive":{"type":"boolean","default":false,"description":"Computed subscription state for the effective check timestamp."},"space_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"current_space_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the current space (resolved)"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"Translations for additional languages (excludes base language)"},"settings":{"type":"object","additionalProperties":true,"description":"Resource-specific settings and metadata"},"currentLocation":{"anyOf":[{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}],"description":"Geographic coordinates (latitude/longitude) of resource location"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","key","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_type":{"type":"string"},"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","contact_type","value"],"additionalProperties":false}},"totalVisits":{"type":"integer","minimum":0,"description":"Current aggregated visit counter returned in detail responses and visit summary payloads."},"lastVisitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."},"mainMedia":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_url":{"type":"string","format":"uri","description":"Default optimized delivery URL selected by entity media mapping rules."},"original_url":{"type":"string","format":"uri","description":"Explicit signed URL for the original/current media bytes."},"current_version":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}],"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."},"has_thumbnails":{"type":"boolean","description":"Whether thumbnail variants are available for this media file"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Thumbnail URL (small variant) for display"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","media_file_id","is_main","sort_order","public_url","original_url","current_version","has_thumbnails"],"additionalProperties":false},{"type":"null"}],"description":"Main media link for this resource. Use media entity endpoints for the full media collection."}},"required":["id","type","name","status","typeName","typeDefinitionId","created_at","updated_at","manageable","promotionType","promotionPlacement","promotionBadge","promotionRank","promotionStartDate","promotionEndDate","customOrder","subscriptionTypeId","subscription","subscriptionStartDate","subscriptionEndDate","subscriptionActive"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/members":{"get":{"summary":"List resource members","tags":["Resource Members"],"description":"Retrieve all members assigned to a specific resource and their current roles.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"role":{"type":"string","enum":["admin","manager","reader"]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["user_id","role"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"tags":["Resource Members"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string","format":"email"}},"userIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/members/{userId}":{"delete":{"tags":["Resource Members"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"userId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/move":{"post":{"tags":["Resource Move Requests"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetSpaceId":{"type":"string","format":"uuid"},"reason":{"type":"string","maxLength":2000}},"required":["targetSpaceId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"resource_id":{"type":"string","format":"uuid"},"source_space_id":{"type":"string","format":"uuid"},"target_space_id":{"type":"string","format":"uuid"},"requested_by":{"type":"string","format":"uuid"},"status":{"type":"string"},"requires_resource_approval":{"type":"boolean"},"approval_mode":{"type":"string","enum":["resource","target_space"]},"approved_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"target_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"requested_by_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"processed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expires_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","resource_id","source_space_id","target_space_id","requested_by","status","requires_resource_approval","approval_mode","created_at","expires_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/resource-requests":{"get":{"summary":"List resource move requests","tags":["Resource Move Requests"],"description":"Retrieve resource move requests with optional filtering by status and resource.","parameters":[{"schema":{"type":"string","enum":["pending","approved","rejected","resource_moved","completed","cancelled","expired"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"resourceId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"sourceSpaceId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"targetSpaceId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"resource_id":{"type":"string","format":"uuid"},"source_space_id":{"type":"string","format":"uuid"},"target_space_id":{"type":"string","format":"uuid"},"requested_by":{"type":"string","format":"uuid"},"status":{"type":"string"},"requires_resource_approval":{"type":"boolean"},"approval_mode":{"type":"string","enum":["resource","target_space"]},"approved_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"target_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"requested_by_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"processed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expires_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","resource_id","source_space_id","target_space_id","requested_by","status","requires_resource_approval","approval_mode","created_at","expires_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/resource-requests/{id}/approve":{"post":{"tags":["Resource Move Requests"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"resource_id":{"type":"string","format":"uuid"},"source_space_id":{"type":"string","format":"uuid"},"target_space_id":{"type":"string","format":"uuid"},"requested_by":{"type":"string","format":"uuid"},"status":{"type":"string"},"requires_resource_approval":{"type":"boolean"},"approval_mode":{"type":"string","enum":["resource","target_space"]},"approved_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"target_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"requested_by_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"processed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expires_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","resource_id","source_space_id","target_space_id","requested_by","status","requires_resource_approval","approval_mode","created_at","expires_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/resource-requests/{id}/reject":{"post":{"tags":["Resource Move Requests"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rejectionReason":{"type":"string","minLength":1,"maxLength":2000}},"required":["rejectionReason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"resource_id":{"type":"string","format":"uuid"},"source_space_id":{"type":"string","format":"uuid"},"target_space_id":{"type":"string","format":"uuid"},"requested_by":{"type":"string","format":"uuid"},"status":{"type":"string"},"requires_resource_approval":{"type":"boolean"},"approval_mode":{"type":"string","enum":["resource","target_space"]},"approved_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"target_space_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"requested_by_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"processed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expires_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","resource_id","source_space_id","target_space_id","requested_by","status","requires_resource_approval","approval_mode","created_at","expires_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/resource-requests/{id}":{"delete":{"tags":["Resource Move Requests"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/tags":{"get":{"summary":"List resource tags","tags":["Resources"],"description":"Get all tags linked to a resource","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"preferredLanguage","required":false,"description":"ISO 639-1 language code for localized responses"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Localized display name (preferred language with base-language fallback)"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Localized category summaries linked to the tag"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"returnedCount":{"type":"number"},"total":{"type":"number"}},"required":["data","returnedCount"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Link resource tag","tags":["Resources"],"description":"Link a tag to a resource (creates tag if it doesn't exist)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tag_name":{"type":"string","minLength":1,"maxLength":100}},"required":["tag_name"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tag_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tag_id","entity_type","entity_id","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/tags/{tagId}":{"delete":{"summary":"Unlink resource tag","tags":["Resources"],"description":"Unlink a tag from a resource","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"tagId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/categories":{"get":{"summary":"List resource categories","tags":["Resources"],"description":"Get all categories linked to a resource","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"preferredLanguage","required":false,"description":"ISO 639-1 language code for localized responses"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"level":{"type":"number"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string","description":"Localized name (preferred language with EN fallback)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Localized description"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code"},"usage_count":{"type":"number"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","usage_count","created_at","updated_at"],"additionalProperties":false}},"returnedCount":{"type":"number"},"total":{"type":"number"}},"required":["data","returnedCount"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Link resource category","tags":["Resources"],"description":"Link a category to a resource","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"}},"required":["category_id"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"categoryId":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["space","resource","tenant","group"]},"entityId":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","categoryId","entityType","entityId","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/categories/{categoryId}":{"delete":{"summary":"Unlink resource category","tags":["Resources"],"description":"Unlink a category from a resource","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"categoryId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/export":{"get":{"summary":"Export resources","tags":["Resources"],"description":"Export resources to Excel/CSV/TSV","parameters":[{"schema":{"type":"string","enum":["xlsx","csv","tsv","json","json-schema"],"default":"xlsx"},"in":"query","name":"format","required":false,"description":"Export file format (xlsx, csv, tsv)"},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeExample","required":false,"description":"Include example row if data is empty"},{"schema":{"type":"number","minimum":1,"maximum":10000,"default":10000},"in":"query","name":"limit","required":false,"description":"Maximum number of rows to export"},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Offset for pagination"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Binary file download","content":{"application/json":{"schema":{"description":"Binary file download","type":"string","format":"binary"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/resources/import":{"post":{"summary":"Import resources","tags":["Resources"],"description":"Import resources from Excel/CSV/TSV file","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether import completed without critical errors"},"dryRun":{"type":"boolean","description":"Whether this was a validation-only dry run"},"entityType":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"],"description":"Entity type that was imported"},"stats":{"type":"object","properties":{"created":{"type":"number","description":"Number of entities created"},"updated":{"type":"number","description":"Number of entities updated"},"skipped":{"type":"number","description":"Number of entities skipped (merge strategy)"},"duplicates":{"type":"number","description":"Number of duplicate entries detected"},"errors":{"type":"number","description":"Number of rows with errors"}},"required":["created","updated","skipped","duplicates","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","description":"Row number (1-based, including header)"},"column":{"type":"string","description":"Column name where error occurred"},"value":{"type":"string","description":"Value that caused the error"},"identifier":{"type":"string","description":"Entity identifier (name, key, id)"},"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["INVALID_FORMAT","REQUIRED_FIELD","INVALID_UUID","DUPLICATE_ENTRY","REFERENCE_NOT_FOUND","VALIDATION_ERROR","IMPORT_ERROR","FILE_ERROR"]}},"required":["identifier","message","code"],"additionalProperties":false},"description":"Detailed error information per row"},"processedRows":{"type":"number","description":"Total number of rows processed"},"totalRows":{"type":"number","description":"Total number of rows in file"}},"required":["success","dryRun","entityType","stats","warnings","errors"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/chat/actors/conversations":{"post":{"summary":"Create or return an actor-owned chat conversation","tags":["Chat"],"description":"Create a durable resource-owned or space-owned conversation for a customer-facing user, optionally posting an opening message. Non-owner users can start the actor thread for themselves, and eligible owners can start the same actor thread toward any non-owner tenant user.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ownerActor"],"properties":{"ownerActor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["resource","space"]},"resourceId":{"type":"string","format":"uuid"},"spaceId":{"type":"string","format":"uuid"}},"additionalProperties":false,"allOf":[{"if":{"properties":{"type":{"enum":["resource"]}}},"then":{"required":["resourceId"]}},{"if":{"properties":{"type":{"enum":["space"]}}},"then":{"required":["spaceId"]}}]},"participantUserId":{"type":"string","format":"uuid"},"initialMessage":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","conversationType","peer","unreadCount","lastMessageAt","lastReadAt","actorContext","participants"],"properties":{"id":{"type":"string","format":"uuid"},"conversationType":{"type":"string","enum":["direct","resource","space","group"]},"peer":{"type":"object","required":["type","displayName","fullName"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}],"additionalProperties":false},"unreadCount":{"type":"integer","minimum":0},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageSenderUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorContext":{"anyOf":[{"type":"object","required":["ownerActor","initiatingUserId","sharedOwnerVisibility","assignment"],"properties":{"ownerActor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},"initiatingUserId":{"type":"string","format":"uuid"},"sharedOwnerVisibility":{"type":"string","enum":["shared_owners","assigned_owner_only"]},"assignment":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["pending","accepted","assigned","reassigned"]},"assignedOwnerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignmentUpdatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTakenOverByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastTakenOverAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReassignedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastReassignedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"participants":{"type":"array","items":{"type":"object","required":["userId","role","state","displayName","fullName"],"properties":{"userId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["participant","customer","owner","assignee","watcher"]},"state":{"type":"string","enum":["invited","pending","accepted","active","archived"]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkedActor":{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},{"type":"null"}]},"unreadCount":{"type":"integer","minimum":0},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"maxItems":50},"onlineState":{"type":"string","enum":["online","recently_active","offline"],"description":"Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/conversations/{conversationId}/assignment":{"patch":{"summary":"Update actor-owned chat assignment state","tags":["Chat"],"description":"Accept, assign, take over, or reassign responsibility for an actor-owned chat conversation while preserving shared-owner visibility.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["pending","accepted","assigned","reassigned"]},"assignedOwnerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","conversationType","peer","unreadCount","lastMessageAt","lastReadAt","actorContext","participants"],"properties":{"id":{"type":"string","format":"uuid"},"conversationType":{"type":"string","enum":["direct","resource","space","group"]},"peer":{"type":"object","required":["type","displayName","fullName"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}],"additionalProperties":false},"unreadCount":{"type":"integer","minimum":0},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageSenderUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorContext":{"anyOf":[{"type":"object","required":["ownerActor","initiatingUserId","sharedOwnerVisibility","assignment"],"properties":{"ownerActor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},"initiatingUserId":{"type":"string","format":"uuid"},"sharedOwnerVisibility":{"type":"string","enum":["shared_owners","assigned_owner_only"]},"assignment":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["pending","accepted","assigned","reassigned"]},"assignedOwnerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignmentUpdatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTakenOverByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastTakenOverAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReassignedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastReassignedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"participants":{"type":"array","items":{"type":"object","required":["userId","role","state","displayName","fullName"],"properties":{"userId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["participant","customer","owner","assignee","watcher"]},"state":{"type":"string","enum":["invited","pending","accepted","active","archived"]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkedActor":{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},{"type":"null"}]},"unreadCount":{"type":"integer","minimum":0},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"maxItems":50},"onlineState":{"type":"string","enum":["online","recently_active","offline"],"description":"Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/broadcast":{"post":{"summary":"Broadcast a tenant-wide admin notification","tags":["Chat Admin"],"description":"Publish one durable tenant-wide admin broadcast notification from the current tenant admin to every active user in the tenant.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["targetUserCount","conversationCount","deliveredMessageCount"],"properties":{"targetUserCount":{"type":"integer","minimum":0},"conversationCount":{"type":"integer","minimum":0},"deliveredMessageCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/overview":{"get":{"summary":"Get tenant chat admin overview","tags":["Chat Admin"],"description":"Return the tenant-wide chat overview metrics used by the tenant admin overview page. Read access is limited to tenant admins and system admins.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["activeConversationCount","messagesLast24h","pushQueueDepth","pushFailureRate","activeConnections","messageRateLimit"],"properties":{"activeConversationCount":{"type":"integer","minimum":0},"messagesLast24h":{"type":"integer","minimum":0},"pushQueueDepth":{"type":"integer","minimum":0},"pushFailureRate":{"type":"number","minimum":0},"activeConnections":{"type":"integer","minimum":0},"messageRateLimit":{"type":"object","required":["activeSends","sendsInWindow","remainingInWindow","maxConcurrent","maxPerMinute","rateLimitedCount","utilizationPercent","lastMessageAt","lastRateLimitedAt"],"properties":{"activeSends":{"type":"integer","minimum":0},"sendsInWindow":{"type":"integer","minimum":0},"remainingInWindow":{"type":"integer","minimum":0},"maxConcurrent":{"type":"integer","minimum":1},"maxPerMinute":{"type":"integer","minimum":1},"rateLimitedCount":{"type":"integer","minimum":0},"utilizationPercent":{"type":"integer","minimum":0,"maximum":100},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastRateLimitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/statistics":{"get":{"summary":"Get tenant chat admin statistics","tags":["Chat Admin"],"description":"Return a reduced tenant-wide operational statistics set for chat conversations, seven-day message volume, unread state, and push-delivery backlog/failures. Read access is limited to tenant admins and system admins.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["conversationCount","messagesLast7d","unreadMembershipCount","queuedDeliveryCount","failedDeliveryCount"],"properties":{"conversationCount":{"type":"integer","minimum":0},"messagesLast7d":{"type":"integer","minimum":0},"unreadMembershipCount":{"type":"integer","minimum":0},"queuedDeliveryCount":{"type":"integer","minimum":0},"failedDeliveryCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/diagnostic-summary":{"get":{"summary":"Get tenant chat diagnostic summary","tags":["Chat Admin"],"description":"Return the tenant-scoped diagnostic summary for push-device health and recent push-delivery outcomes. Read access is limited to tenant admins and system admins.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["pushEnabled","providerRoutingMode","activeDeviceCount","invalidDeviceCount","queuedDeliveryCount","suppressedDeliveryCount","failedDeliveryCount","lastQueuedDeliveryAt","lastFailedDeliveryAt"],"properties":{"pushEnabled":{"type":"boolean"},"providerRoutingMode":{"type":"string","enum":["managed","disabled"]},"activeDeviceCount":{"type":"integer","minimum":0},"invalidDeviceCount":{"type":"integer","minimum":0},"queuedDeliveryCount":{"type":"integer","minimum":0},"suppressedDeliveryCount":{"type":"integer","minimum":0},"failedDeliveryCount":{"type":"integer","minimum":0},"lastQueuedDeliveryAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastFailedDeliveryAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/configuration":{"get":{"summary":"Get tenant chat admin configuration","tags":["Chat Admin"],"description":"Return the tenant-scoped chat configuration that drives pagination, online-state policy, and retention defaults.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["pushEnabled","onlineStateEnabled","defaultConversationPageSize","defaultTimelinePageSize","messageRetentionDays","initiationPolicy"],"properties":{"pushEnabled":{"type":"boolean"},"onlineStateEnabled":{"type":"boolean"},"defaultConversationPageSize":{"type":"integer"},"defaultTimelinePageSize":{"type":"integer"},"messageRetentionDays":{"type":"integer"},"initiationPolicy":{"type":"object","required":["direct","group"],"properties":{"direct":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"resource":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"space":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false}},"additionalProperties":false},"group":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"resource":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"space":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update tenant chat admin configuration","tags":["Chat Admin"],"description":"Update tenant-scoped chat configuration values. Write access is limited to tenant admins and system admins.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pushEnabled":{"type":"boolean"},"onlineStateEnabled":{"type":"boolean"},"defaultConversationPageSize":{"type":"integer","minimum":1,"maximum":50},"defaultTimelinePageSize":{"type":"integer","minimum":1,"maximum":100},"messageRetentionDays":{"type":"integer","minimum":1,"maximum":3650},"initiationPolicy":{"type":"object","required":["direct","group"],"properties":{"direct":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"resource":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"space":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false}},"additionalProperties":false},"group":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"resource":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"space":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["pushEnabled","onlineStateEnabled","defaultConversationPageSize","defaultTimelinePageSize","messageRetentionDays","initiationPolicy"],"properties":{"pushEnabled":{"type":"boolean"},"onlineStateEnabled":{"type":"boolean"},"defaultConversationPageSize":{"type":"integer"},"defaultTimelinePageSize":{"type":"integer"},"messageRetentionDays":{"type":"integer"},"initiationPolicy":{"type":"object","required":["direct","group"],"properties":{"direct":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"resource":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"space":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false}},"additionalProperties":false},"group":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"resource":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false},"space":{"type":"object","required":["user","resource","space"],"properties":{"user":{"type":"string","enum":["allow","deny"]},"resource":{"type":"string","enum":["allow","deny"]},"space":{"type":"string","enum":["allow","deny"]}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/push-configuration":{"get":{"summary":"Get tenant chat push configuration","tags":["Chat Admin"],"description":"Return tenant-scoped chat push policy including provider routing mode, default TTL, suppressPushWhenActiveInConversation, quietHoursSupported capability flag, fanout mode, and appOrigin used to build absolute webpush deeplinks.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["providerRoutingMode","pushEnabled","defaultTtlSeconds","quietHoursSupported","suppressPushWhenActiveInConversation","pushFanoutMode","appOrigin"],"properties":{"providerRoutingMode":{"type":"string","enum":["managed","disabled"]},"pushEnabled":{"type":"boolean"},"defaultTtlSeconds":{"type":"integer","minimum":0,"maximum":259200},"quietHoursSupported":{"type":"boolean"},"suppressPushWhenActiveInConversation":{"type":"boolean"},"pushFanoutMode":{"type":"string","enum":["all_active_devices"]},"appOrigin":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048,"pattern":"^https://[A-Za-z0-9.-]+(:[0-9]{1,5})?$|^http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?$"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update tenant chat push configuration","tags":["Chat Admin"],"description":"Update tenant-scoped chat push delivery policy values. quietHoursSupported is a capability flag for clients; no tenant quiet-hours schedule is enforced by this endpoint yet. appOrigin must be an absolute origin and is used for push click-through URL generation.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"providerRoutingMode":{"type":"string","enum":["managed","disabled"]},"pushEnabled":{"type":"boolean"},"defaultTtlSeconds":{"type":"integer","minimum":0,"maximum":259200},"quietHoursSupported":{"type":"boolean"},"suppressPushWhenActiveInConversation":{"type":"boolean"},"pushFanoutMode":{"type":"string","enum":["all_active_devices"]},"appOrigin":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048,"pattern":"^https://[A-Za-z0-9.-]+(:[0-9]{1,5})?$|^http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?$"},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["providerRoutingMode","pushEnabled","defaultTtlSeconds","quietHoursSupported","suppressPushWhenActiveInConversation","pushFanoutMode","appOrigin"],"properties":{"providerRoutingMode":{"type":"string","enum":["managed","disabled"]},"pushEnabled":{"type":"boolean"},"defaultTtlSeconds":{"type":"integer","minimum":0,"maximum":259200},"quietHoursSupported":{"type":"boolean"},"suppressPushWhenActiveInConversation":{"type":"boolean"},"pushFanoutMode":{"type":"string","enum":["all_active_devices"]},"appOrigin":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048,"pattern":"^https://[A-Za-z0-9.-]+(:[0-9]{1,5})?$|^http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?$"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/push-configuration/test":{"post":{"summary":"Run tenant chat push readiness check","tags":["Chat Admin"],"description":"Return a non-delivery readiness summary for tenant-scoped chat push configuration and a target user.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetUserId":{"type":"string","format":"uuid"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["targetUserId","pushEnabled","providerRoutingMode","activeDeviceCount","hasActiveDevices","queuedDeliveryCount","failedDeliveryCount"],"properties":{"targetUserId":{"type":"string","format":"uuid"},"pushEnabled":{"type":"boolean"},"providerRoutingMode":{"type":"string","enum":["managed","disabled"]},"activeDeviceCount":{"type":"integer","minimum":0},"hasActiveDevices":{"type":"boolean"},"queuedDeliveryCount":{"type":"integer","minimum":0},"failedDeliveryCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/presence/roster":{"post":{"summary":"Resolve tenant chat presence roster","tags":["Chat Admin"],"description":"Return automatic and effective chat presence state for a selected roster of user, resource, and space actors.","requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Tenant-admin roster presence resolution request. Clients submit bounded actor targets and render the returned automatic/effective presence states as roster attributes. This is not a polling contract.","required":["actors"],"properties":{"actors":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","description":"Presence actor target. Send exactly one id field matching type: userId for user, resourceId for resource, or spaceId for space.","properties":{"type":{"type":"string","enum":["user","resource","space"],"description":"Actor kind whose chat presence is being resolved or manually overridden."},"userId":{"type":"string","format":"uuid","description":"Required only when type=user."},"resourceId":{"type":"string","format":"uuid","description":"Required only when type=resource. Use this for seller/resource presence in customer-facing chat."},"spaceId":{"type":"string","format":"uuid","description":"Required only when type=space."}},"additionalProperties":false,"anyOf":[{"required":["type","userId"]},{"required":["type","resourceId"]},{"required":["type","spaceId"]}]}}},"additionalProperties":false}}},"required":true,"description":"Tenant-admin roster presence resolution request. Clients submit bounded actor targets and render the returned automatic/effective presence states as roster attributes. This is not a polling contract."},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","description":"Resolved roster presence state for a user, resource, or space actor. Render effectiveState as the roster indicator, preserve automaticState for diagnostics/secondary UI, and do not derive actor presence from client polling timers.","required":["actor","automaticState","effectiveState","effectiveSource","manualOverrideAllowed","manualState","observedAt"],"properties":{"actor":{"oneOf":[{"type":"object","required":["type","userId","label"],"properties":{"type":{"enum":["user"]},"userId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["type","resourceId","label"],"properties":{"type":{"enum":["resource"]},"resourceId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["type","spaceId","label"],"properties":{"type":{"enum":["space"]},"spaceId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false}]},"automaticState":{"type":"string","enum":["online","recently_active","offline"]},"effectiveState":{"type":"string","enum":["online","recently_active","offline"]},"effectiveSource":{"type":"string","enum":["automatic","manual"]},"manualOverrideAllowed":{"type":"boolean"},"manualState":{"anyOf":[{"type":"string","enum":["online","recently_active","offline"]},{"type":"null"}]},"observedAt":{"type":"string","format":"date-time"},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/presence/actors":{"patch":{"summary":"Update tenant chat actor presence override","tags":["Chat Admin"],"description":"Restrict or allow self-service manual presence for a user, resource, or space actor and optionally set its current manual state. Tenant admins can set manualState even when self-service is restricted.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["actor"],"properties":{"actor":{"type":"object","description":"Presence actor target. Send exactly one id field matching type: userId for user, resourceId for resource, or spaceId for space.","properties":{"type":{"type":"string","enum":["user","resource","space"],"description":"Actor kind whose chat presence is being resolved or manually overridden."},"userId":{"type":"string","format":"uuid","description":"Required only when type=user."},"resourceId":{"type":"string","format":"uuid","description":"Required only when type=resource. Use this for seller/resource presence in customer-facing chat."},"spaceId":{"type":"string","format":"uuid","description":"Required only when type=space."}},"additionalProperties":false,"anyOf":[{"required":["type","userId"]},{"required":["type","resourceId"]},{"required":["type","spaceId"]}]},"manualOverrideAllowed":{"type":"boolean","description":"Allows or restricts self-service manual presence for the actor. Default policy allows manual changes unless this actor is explicitly restricted."},"manualState":{"description":"Manual effective state to apply as a tenant admin. Use null to clear the manual state and return to automatic presence. Tenant admins may set this even when self-service is restricted.","anyOf":[{"type":"string","enum":["online","recently_active","offline"]},{"type":"null"}]}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","description":"Resolved roster presence state for a user, resource, or space actor. Render effectiveState as the roster indicator, preserve automaticState for diagnostics/secondary UI, and do not derive actor presence from client polling timers.","required":["actor","automaticState","effectiveState","effectiveSource","manualOverrideAllowed","manualState","observedAt"],"properties":{"actor":{"oneOf":[{"type":"object","required":["type","userId","label"],"properties":{"type":{"enum":["user"]},"userId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["type","resourceId","label"],"properties":{"type":{"enum":["resource"]},"resourceId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["type","spaceId","label"],"properties":{"type":{"enum":["space"]},"spaceId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false}]},"automaticState":{"type":"string","enum":["online","recently_active","offline"]},"effectiveState":{"type":"string","enum":["online","recently_active","offline"]},"effectiveSource":{"type":"string","enum":["automatic","manual"]},"manualOverrideAllowed":{"type":"boolean"},"manualState":{"anyOf":[{"type":"string","enum":["online","recently_active","offline"]},{"type":"null"}]},"observedAt":{"type":"string","format":"date-time"},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/admin/push-deliveries":{"get":{"summary":"List tenant chat push deliveries","tags":["Chat Admin"],"description":"Return the tenant-scoped push delivery diagnostics list. Read access is limited to tenant admins and system admins.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","enum":["queued","sending","sent","delivered","suppressed","failed"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","conversationId","provider","status","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"provider":{"type":"string"},"status":{"type":"string","enum":["queued","sending","sent","delivered","suppressed","failed"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/lookup/actor-codes":{"post":{"summary":"Issue or reuse a chat actor short code","tags":["Chat"],"description":"Return the tenant-scoped short code for a visible user, resource, or space actor so apps can share a compact identifier instead of raw UUIDs.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["actor"],"properties":{"actor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]}]}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["code","actor"],"properties":{"code":{"type":"string"},"actor":{"type":"object","required":["type","displayName"],"properties":{"type":{"type":"string","enum":["user","resource","space"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/lookup/actor-codes/resolve":{"post":{"summary":"Resolve a chat actor short code","tags":["Chat"],"description":"Resolve a tenant-scoped short code back to the canonical actor identity and display label for chat initiation.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","minLength":6,"maxLength":16,"pattern":"^[A-HJ-NP-Z2-9]+$"}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["code","actor"],"properties":{"code":{"type":"string"},"actor":{"type":"object","required":["type","displayName"],"properties":{"type":{"type":"string","enum":["user","resource","space"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/bootstrap":{"get":{"summary":"Get chat bootstrap payload","tags":["Chat"],"description":"Return unread totals, bounded conversation summaries, online-state policy, and realtime bootstrap data.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["unreadTotal","conversations","onlineStatePolicy","realtime"],"properties":{"unreadTotal":{"type":"integer","minimum":0},"conversations":{"type":"array","items":{"type":"object","required":["id","conversationType","peer","unreadCount","lastMessageAt","lastReadAt","actorContext","participants"],"properties":{"id":{"type":"string","format":"uuid"},"conversationType":{"type":"string","enum":["direct","resource","space","group"]},"peer":{"type":"object","required":["type","displayName","fullName"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}],"additionalProperties":false},"unreadCount":{"type":"integer","minimum":0},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageSenderUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorContext":{"anyOf":[{"type":"object","required":["ownerActor","initiatingUserId","sharedOwnerVisibility","assignment"],"properties":{"ownerActor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},"initiatingUserId":{"type":"string","format":"uuid"},"sharedOwnerVisibility":{"type":"string","enum":["shared_owners","assigned_owner_only"]},"assignment":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["pending","accepted","assigned","reassigned"]},"assignedOwnerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignmentUpdatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTakenOverByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastTakenOverAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReassignedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastReassignedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"participants":{"type":"array","items":{"type":"object","required":["userId","role","state","displayName","fullName"],"properties":{"userId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["participant","customer","owner","assignee","watcher"]},"state":{"type":"string","enum":["invited","pending","accepted","active","archived"]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkedActor":{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},{"type":"null"}]},"unreadCount":{"type":"integer","minimum":0},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"maxItems":50},"onlineState":{"type":"string","enum":["online","recently_active","offline"],"description":"Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."}},"additionalProperties":false},"maxItems":20},"onlineStatePolicy":{"type":"object","required":["approximate","source","states","recentlyActiveWindowSeconds","refreshTriggers","maxTrackedParticipants"],"properties":{"approximate":{"type":"boolean","enum":[true]},"source":{"type":"string","description":"Greenfield presence source contract. The backend derives roster presence from Centrifugo presence_stats on dedicated presence-only channels.","enum":["centrifugo_presence_channel"]},"states":{"type":"array","description":"Canonical presence states supported by the current backend contract.","minItems":3,"maxItems":3,"items":{"type":"string","enum":["online","recently_active","offline"]}},"recentlyActiveWindowSeconds":{"type":"integer","description":"A user is recently_active when they were observed online within the last 15 seconds but are not currently present.","enum":[15]},"refreshTriggers":{"type":"array","description":"Client events that may trigger one bounded GET /api/v1/secure/chat/online-state roster snapshot. These are event triggers, not a polling cadence.","minItems":5,"maxItems":5,"items":{"type":"string","enum":["bootstrap","reconnect","online_state_join","online_state_leave","conversation_visibility_change"]}},"maxTrackedParticipants":{"type":"integer","minimum":1,"maximum":50}},"additionalProperties":false},"realtime":{"type":"object","required":["token","expiresAt","transport","personalChannel","presenceChannel"],"properties":{"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"personalChannel":{"type":"string"},"presenceChannel":{"type":"string","description":"Current user presence-only Centrifugo channel. Clients subscribe to this channel so peers can resolve online-state through event-driven roster updates without granting inbox access."},"refreshRequired":{"type":"boolean"},"transport":{"type":"object","required":["wsEndpoint","useTls"],"properties":{"wsEndpoint":{"type":"string"},"useTls":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/conversations":{"get":{"summary":"List chat conversations","tags":["Chat"],"description":"Return the authenticated user's inbox-style conversation list with cursor pagination.","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":50},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","conversationType","peer","unreadCount","lastMessageAt","lastReadAt","actorContext","participants"],"properties":{"id":{"type":"string","format":"uuid"},"conversationType":{"type":"string","enum":["direct","resource","space","group"]},"peer":{"type":"object","required":["type","displayName","fullName"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}],"additionalProperties":false},"unreadCount":{"type":"integer","minimum":0},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageSenderUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorContext":{"anyOf":[{"type":"object","required":["ownerActor","initiatingUserId","sharedOwnerVisibility","assignment"],"properties":{"ownerActor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},"initiatingUserId":{"type":"string","format":"uuid"},"sharedOwnerVisibility":{"type":"string","enum":["shared_owners","assigned_owner_only"]},"assignment":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["pending","accepted","assigned","reassigned"]},"assignedOwnerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignmentUpdatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTakenOverByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastTakenOverAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReassignedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastReassignedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"participants":{"type":"array","items":{"type":"object","required":["userId","role","state","displayName","fullName"],"properties":{"userId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["participant","customer","owner","assignee","watcher"]},"state":{"type":"string","enum":["invited","pending","accepted","active","archived"]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkedActor":{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},{"type":"null"}]},"unreadCount":{"type":"integer","minimum":0},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"maxItems":50},"onlineState":{"type":"string","enum":["online","recently_active","offline"],"description":"Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."}},"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create or return a direct chat conversation","tags":["Chat"],"description":"Canonicalize a direct participant pair, return the existing conversation when present, or create a new durable direct conversation with an optional opening message.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["participantUserId"],"properties":{"participantUserId":{"type":"string","format":"uuid"},"initialMessage":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","conversationType","peer","unreadCount","lastMessageAt","lastReadAt","actorContext","participants"],"properties":{"id":{"type":"string","format":"uuid"},"conversationType":{"type":"string","enum":["direct","resource","space","group"]},"peer":{"type":"object","required":["type","displayName","fullName"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}],"additionalProperties":false},"unreadCount":{"type":"integer","minimum":0},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageSenderUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorContext":{"anyOf":[{"type":"object","required":["ownerActor","initiatingUserId","sharedOwnerVisibility","assignment"],"properties":{"ownerActor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},"initiatingUserId":{"type":"string","format":"uuid"},"sharedOwnerVisibility":{"type":"string","enum":["shared_owners","assigned_owner_only"]},"assignment":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["pending","accepted","assigned","reassigned"]},"assignedOwnerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignmentUpdatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTakenOverByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastTakenOverAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReassignedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastReassignedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"participants":{"type":"array","items":{"type":"object","required":["userId","role","state","displayName","fullName"],"properties":{"userId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["participant","customer","owner","assignee","watcher"]},"state":{"type":"string","enum":["invited","pending","accepted","active","archived"]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkedActor":{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},{"type":"null"}]},"unreadCount":{"type":"integer","minimum":0},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"maxItems":50},"onlineState":{"type":"string","enum":["online","recently_active","offline"],"description":"Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/conversations/{conversationId}":{"get":{"summary":"Get a chat conversation summary","tags":["Chat"],"description":"Return the durable summary metadata for one conversation visible to the authenticated user.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","conversationType","peer","unreadCount","lastMessageAt","lastReadAt","actorContext","participants"],"properties":{"id":{"type":"string","format":"uuid"},"conversationType":{"type":"string","enum":["direct","resource","space","group"]},"peer":{"type":"object","required":["type","displayName","fullName"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}],"additionalProperties":false},"unreadCount":{"type":"integer","minimum":0},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageSenderUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorContext":{"anyOf":[{"type":"object","required":["ownerActor","initiatingUserId","sharedOwnerVisibility","assignment"],"properties":{"ownerActor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},"initiatingUserId":{"type":"string","format":"uuid"},"sharedOwnerVisibility":{"type":"string","enum":["shared_owners","assigned_owner_only"]},"assignment":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["pending","accepted","assigned","reassigned"]},"assignedOwnerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignmentUpdatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTakenOverByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastTakenOverAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReassignedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastReassignedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"participants":{"type":"array","items":{"type":"object","required":["userId","role","state","displayName","fullName"],"properties":{"userId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["participant","customer","owner","assignee","watcher"]},"state":{"type":"string","enum":["invited","pending","accepted","active","archived"]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkedActor":{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},{"type":"null"}]},"unreadCount":{"type":"integer","minimum":0},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"maxItems":50},"onlineState":{"type":"string","enum":["online","recently_active","offline"],"description":"Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/conversations/{conversationId}/messages":{"get":{"summary":"List chat messages","tags":["Chat"],"description":"Return a bounded durable message timeline for one visible conversation with latest-page cursor pagination and forward delta sync.","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"after","required":false,"description":"Message id checkpoint for forward delta sync. Returns visible messages committed after this message in sentAt/id order."},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"afterSentAt","required":false,"description":"Timestamp checkpoint for forward delta sync when a message id is not available. Prefer after for exact tie handling."},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","conversationId","senderUserId","content","mediaAttachments","sentAt"],"properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"senderUserId":{"type":"string","format":"uuid"},"clientMessageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"content":{"type":"string"},"mediaAttachments":{"description":"Backend-enriched attachment metadata for the message. Use only this block for previews and downloads instead of inferring storage paths or thumbnail variants in the client.","type":"array","items":{"type":"object","required":["id","mediaFileId","mimeType","fileSizeBytes","publicUrl","thumbnailUrls"],"properties":{"id":{"type":"string","format":"uuid"},"mediaFileId":{"type":"string","format":"uuid"},"mimeType":{"type":"string"},"fileSizeBytes":{"type":"integer","minimum":0},"originalFilename":{"anyOf":[{"type":"string"},{"type":"null"}]},"publicUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Signed download URL for the original media file when available. Use this only for explicit open/download actions, not normal image-message rendering."},"thumbnailUrls":{"description":"Normalized optimized image preview URLs for conversation rendering. When present, only the canonical small, medium, large, and preview keys may appear; non-canonical media metadata variants are filtered out. Null means no canonical preview thumbnails are available for the attachment.","anyOf":[{"type":"object","properties":{"small":{"type":"string","description":"Signed URL for the small image thumbnail variant."},"medium":{"type":"string","description":"Signed URL for the medium image thumbnail variant."},"large":{"type":"string","description":"Signed URL for the large image thumbnail variant."},"preview":{"type":"string","description":"Signed URL for the preview image thumbnail variant."}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}},"sentAt":{"type":"string","format":"date-time"},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Send chat message","tags":["Chat"],"description":"Create a durable chat message for one visible conversation and update the bounded unread state.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"clientMessageId":{"type":"string","minLength":1,"maxLength":100},"content":{"type":"string","maxLength":4000},"mediaAttachments":{"description":"Optional uploaded media references for attachment-only or mixed chat messages. Upload each file first through POST /api/v1/services/media/upload and send the returned mediaFileId values here.","type":"array","maxItems":10,"items":{"type":"object","required":["mediaFileId"],"properties":{"mediaFileId":{"type":"string","format":"uuid","description":"Canonical id of an already uploaded PVE media file to attach to the message."}},"additionalProperties":false}}},"additionalProperties":false,"required":["clientMessageId"],"anyOf":[{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1}}},{"type":"object","required":["mediaAttachments"],"properties":{"mediaAttachments":{"type":"array","minItems":1}}}]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"conversationId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","conversationId","senderUserId","content","mediaAttachments","sentAt"],"properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"senderUserId":{"type":"string","format":"uuid"},"clientMessageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"content":{"type":"string"},"mediaAttachments":{"description":"Backend-enriched attachment metadata for the message. Use only this block for previews and downloads instead of inferring storage paths or thumbnail variants in the client.","type":"array","items":{"type":"object","required":["id","mediaFileId","mimeType","fileSizeBytes","publicUrl","thumbnailUrls"],"properties":{"id":{"type":"string","format":"uuid"},"mediaFileId":{"type":"string","format":"uuid"},"mimeType":{"type":"string"},"fileSizeBytes":{"type":"integer","minimum":0},"originalFilename":{"anyOf":[{"type":"string"},{"type":"null"}]},"publicUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Signed download URL for the original media file when available. Use this only for explicit open/download actions, not normal image-message rendering."},"thumbnailUrls":{"description":"Normalized optimized image preview URLs for conversation rendering. When present, only the canonical small, medium, large, and preview keys may appear; non-canonical media metadata variants are filtered out. Null means no canonical preview thumbnails are available for the attachment.","anyOf":[{"type":"object","properties":{"small":{"type":"string","description":"Signed URL for the small image thumbnail variant."},"medium":{"type":"string","description":"Signed URL for the medium image thumbnail variant."},"large":{"type":"string","description":"Signed URL for the large image thumbnail variant."},"preview":{"type":"string","description":"Signed URL for the preview image thumbnail variant."}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}},"sentAt":{"type":"string","format":"date-time"},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/conversations/{conversationId}/read-state":{"patch":{"summary":"Update chat read state","tags":["Chat"],"description":"Update the durable read cursor for one visible conversation.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lastSeenMessageId":{"type":"string","format":"uuid"},"readCursorAt":{"type":"string","format":"date-time"}},"additionalProperties":false,"anyOf":[{"type":"object","required":["lastSeenMessageId"]},{"type":"object","required":["readCursorAt"]}]}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","conversationType","peer","unreadCount","lastMessageAt","lastReadAt","actorContext","participants"],"properties":{"id":{"type":"string","format":"uuid"},"conversationType":{"type":"string","enum":["direct","resource","space","group"]},"peer":{"type":"object","required":["type","displayName","fullName"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"displayName":{"type":"string"},"fullName":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}],"additionalProperties":false},"unreadCount":{"type":"integer","minimum":0},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageSenderUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorContext":{"anyOf":[{"type":"object","required":["ownerActor","initiatingUserId","sharedOwnerVisibility","assignment"],"properties":{"ownerActor":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},"initiatingUserId":{"type":"string","format":"uuid"},"sharedOwnerVisibility":{"type":"string","enum":["shared_owners","assigned_owner_only"]},"assignment":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["pending","accepted","assigned","reassigned"]},"assignedOwnerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignmentUpdatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTakenOverByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastTakenOverAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastReassignedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastReassignedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"participants":{"type":"array","items":{"type":"object","required":["userId","role","state","displayName","fullName"],"properties":{"userId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["participant","customer","owner","assignee","watcher"]},"state":{"type":"string","enum":["invited","pending","accepted","active","archived"]},"displayName":{"type":"string"},"fullName":{"type":"string"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkedActor":{"anyOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["user","resource","space","group"]},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"groupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"anyOf":[{"type":"object","properties":{"type":{"enum":["user"]}},"required":["userId"]},{"type":"object","properties":{"type":{"enum":["resource"]}},"required":["resourceId"]},{"type":"object","properties":{"type":{"enum":["space"]}},"required":["spaceId"]},{"type":"object","properties":{"type":{"enum":["group"]}},"required":["groupId"]}]},{"type":"null"}]},"unreadCount":{"type":"integer","minimum":0},"lastReadAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"maxItems":50},"onlineState":{"type":"string","enum":["online","recently_active","offline"],"description":"Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/online-state":{"get":{"summary":"Get chat online state","tags":["Chat"],"description":"Return approximate online-state snapshots for the users the client should currently surface. Direct chats resolve the peer user. Actor-owned customer views resolve the assigned owner when present, otherwise another visible owner-side participant; owner-side views resolve the customer.","parameters":[{"schema":{"type":"array","maxItems":50,"items":{"type":"string","format":"uuid"}},"in":"query","name":"participantUserIds","required":false,"description":"Optional explicit user ids whose approximate chat online state should be returned. Use this only for event-triggered roster snapshots when the client already knows the concrete visible users it needs to surface, such as a direct peer, an assigned owner, or another visible actor-side participant. Do not poll this endpoint."},{"schema":{"type":"boolean"},"in":"query","name":"useVisibleConversationSet","required":false,"description":"When true, derive the tracked users from the caller's visible conversation set for an event-triggered roster snapshot. Direct conversations resolve the peer user. Actor-owned customer views resolve the currently assigned owner when present, otherwise another visible owner-side participant; owner-side views resolve the customer. Do not use this as a polling source."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["userId","state","observedAt"],"properties":{"userId":{"type":"string","format":"uuid","description":"The concrete user whose approximate online state was resolved. This may be a direct peer, an assigned owner, another visible owner-side participant, or the customer depending on conversation context."},"state":{"type":"string","enum":["online","recently_active","offline"],"description":"Approximate roster presence state derived from Centrifugo presence-only channels, not a durable chat delivery guarantee. Clients receive it from bootstrap or event-triggered roster snapshots only."},"observedAt":{"type":"string","format":"date-time","description":"Server timestamp for when the presence snapshot was observed."}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/presence/actors/self":{"get":{"summary":"List self-manageable chat presence actors","tags":["Chat"],"description":"Return the authenticated user actor plus any resource or space actors they may administer for chat presence self-service. Manual presence changes are allowed by default; tenant admins can restrict specific actors, which returns manualOverrideAllowed=false.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","description":"Resolved roster presence state for a user, resource, or space actor. Render effectiveState as the roster indicator, preserve automaticState for diagnostics/secondary UI, and do not derive actor presence from client polling timers.","required":["actor","automaticState","effectiveState","effectiveSource","manualOverrideAllowed","manualState","observedAt"],"properties":{"actor":{"oneOf":[{"type":"object","required":["type","userId","label"],"properties":{"type":{"enum":["user"]},"userId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["type","resourceId","label"],"properties":{"type":{"enum":["resource"]},"resourceId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["type","spaceId","label"],"properties":{"type":{"enum":["space"]},"spaceId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false}]},"automaticState":{"type":"string","enum":["online","recently_active","offline"]},"effectiveState":{"type":"string","enum":["online","recently_active","offline"]},"effectiveSource":{"type":"string","enum":["automatic","manual"]},"manualOverrideAllowed":{"type":"boolean"},"manualState":{"anyOf":[{"type":"string","enum":["online","recently_active","offline"]},{"type":"null"}]},"observedAt":{"type":"string","format":"date-time"},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update self chat presence override","tags":["Chat"],"description":"Set or clear the current manual chat presence state for the authenticated user actor or a resource/space actor the user administers. Manual changes are allowed by default unless a tenant admin restricted the specific actor; send manualState=null to return to automatic presence.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["actor","manualState"],"properties":{"actor":{"type":"object","description":"Presence actor target. Send exactly one id field matching type: userId for user, resourceId for resource, or spaceId for space.","properties":{"type":{"type":"string","enum":["user","resource","space"],"description":"Actor kind whose chat presence is being resolved or manually overridden."},"userId":{"type":"string","format":"uuid","description":"Required only when type=user."},"resourceId":{"type":"string","format":"uuid","description":"Required only when type=resource. Use this for seller/resource presence in customer-facing chat."},"spaceId":{"type":"string","format":"uuid","description":"Required only when type=space."}},"additionalProperties":false,"anyOf":[{"required":["type","userId"]},{"required":["type","resourceId"]},{"required":["type","spaceId"]}]},"manualState":{"description":"Manual state for the user actor or a resource/space actor the caller administers. Manual changes are allowed by default unless a tenant admin restricted this actor; use online on active chat page, recently_active on visibility loss if the app wants an away signal, or null to return to automatic presence.","anyOf":[{"type":"string","enum":["online","recently_active","offline"]},{"type":"null"}]}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","description":"Resolved roster presence state for a user, resource, or space actor. Render effectiveState as the roster indicator, preserve automaticState for diagnostics/secondary UI, and do not derive actor presence from client polling timers.","required":["actor","automaticState","effectiveState","effectiveSource","manualOverrideAllowed","manualState","observedAt"],"properties":{"actor":{"oneOf":[{"type":"object","required":["type","userId","label"],"properties":{"type":{"enum":["user"]},"userId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["type","resourceId","label"],"properties":{"type":{"enum":["resource"]},"resourceId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["type","spaceId","label"],"properties":{"type":{"enum":["space"]},"spaceId":{"type":"string","format":"uuid"},"label":{"type":"string"}},"additionalProperties":false}]},"automaticState":{"type":"string","enum":["online","recently_active","offline"]},"effectiveState":{"type":"string","enum":["online","recently_active","offline"]},"effectiveSource":{"type":"string","enum":["automatic","manual"]},"manualOverrideAllowed":{"type":"boolean"},"manualState":{"anyOf":[{"type":"string","enum":["online","recently_active","offline"]},{"type":"null"}]},"observedAt":{"type":"string","format":"date-time"},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/push/devices":{"post":{"summary":"Register chat push device","tags":["Chat"],"description":"Create or refresh one backend-owned chat push device registration for the authenticated user. For webpush clients, pushToken must contain the serialized PushSubscription JSON. Reusing installationId updates the token and metadata instead of creating duplicate rows.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["installationId","platform","pushToken"],"properties":{"installationId":{"type":"string","minLength":1,"maxLength":200},"platform":{"type":"string","enum":["ios","android","web"]},"pushToken":{"type":"string","minLength":1,"maxLength":4096},"appVersion":{"type":"string","maxLength":50},"deviceName":{"type":"string","maxLength":255},"locale":{"type":"string","maxLength":20}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["deviceId","installationId","platform","pushTokenState","updatedAt"],"properties":{"deviceId":{"type":"string","format":"uuid"},"installationId":{"type":"string"},"platform":{"type":"string","enum":["ios","android","web"]},"pushTokenState":{"type":"string","enum":["active","invalid","retired"]},"lastValidatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/push/devices/{deviceId}":{"delete":{"summary":"Retire chat push device","tags":["Chat"],"description":"Retire one backend-owned chat push device registration for the authenticated user.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"deviceId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/push/preferences":{"patch":{"summary":"Update chat push preferences","tags":["Chat"],"description":"Update backend-owned chat push preferences for the authenticated user.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"muteWhileActiveInThread":{"type":"boolean"},"mutedConversationIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["enabled","muteWhileActiveInThread","mutedConversationIds"],"properties":{"enabled":{"type":"boolean"},"muteWhileActiveInThread":{"type":"boolean"},"mutedConversationIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/push/status":{"get":{"summary":"Get chat push status","tags":["Chat"],"description":"Return backend-owned chat push readiness, registered devices, and current user preferences, including muteWhileActiveInThread and per-conversation mute state used by push fanout suppression.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["supported","devices","preferences"],"properties":{"supported":{"type":"boolean"},"devices":{"type":"array","items":{"type":"object","required":["deviceId","installationId","platform","pushTokenState","updatedAt"],"properties":{"deviceId":{"type":"string","format":"uuid"},"installationId":{"type":"string"},"platform":{"type":"string","enum":["ios","android","web"]},"pushTokenState":{"type":"string","enum":["active","invalid","retired"]},"lastValidatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}},"preferences":{"type":"object","required":["enabled","muteWhileActiveInThread","mutedConversationIds"],"properties":{"enabled":{"type":"boolean"},"muteWhileActiveInThread":{"type":"boolean"},"mutedConversationIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/push/focus-state":{"put":{"summary":"Set active chat push focus state","tags":["Chat"],"description":"Heartbeat the currently active conversation focus used for same-conversation push suppression on this user/session. Clients should refresh before ttlSeconds expires while the thread is foregrounded.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["conversationId"],"properties":{"conversationId":{"type":"string","format":"uuid"},"ttlSeconds":{"type":"integer","minimum":15,"maximum":300,"description":"Focus heartbeat TTL in seconds. Defaults to 45 seconds."}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["active","conversationId","lastSeenAt","expiresAt"],"properties":{"active":{"type":"boolean"},"conversationId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastSeenAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Clear active chat push focus state","tags":["Chat"],"description":"Clear active conversation focus so same-conversation push suppression no longer applies to this user/session.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["active","conversationId","lastSeenAt","expiresAt"],"properties":{"active":{"type":"boolean"},"conversationId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lastSeenAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/realtime/session":{"post":{"summary":"Issue chat realtime session","tags":["Chat"],"description":"Issue a Centrifugo connection token and transport configuration for the authenticated user.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["token","expiresAt","transport","personalChannel","presenceChannel"],"properties":{"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"personalChannel":{"type":"string"},"presenceChannel":{"type":"string","description":"Current user presence-only Centrifugo channel. Clients subscribe to this channel so peers can resolve online-state through event-driven roster updates without granting inbox access."},"refreshRequired":{"type":"boolean"},"transport":{"type":"object","required":["wsEndpoint","useTls"],"properties":{"wsEndpoint":{"type":"string"},"useTls":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/chat/realtime/subscriptions":{"post":{"summary":"Issue chat realtime subscription grants","tags":["Chat"],"description":"Issue scoped Centrifugo subscription tokens for authorized chat conversations and optional approximate online-state tracking. Online-state grants target presence-only channels for the concrete users implied by the visible conversation memberships.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["conversationIds"],"properties":{"conversationIds":{"description":"Visible conversation ids that need scoped Centrifugo subscription grants.","type":"array","maxItems":50,"items":{"type":"string","format":"uuid"}},"includeOnlineState":{"type":"boolean","description":"Also issue online-state event grants for the tracked users implied by the requested visible roster. These grants are derived from visible conversation membership, not only direct-chat peer columns, so actor-owned chats cover assigned owners, shared owners, watchers, and customer participants as needed. Clients use these grants for event-driven state changes, not polling."}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["subscriptions","onlineStateSubscriptions"],"properties":{"subscriptions":{"description":"Per-conversation Centrifugo grants for the visible conversation set.","type":"array","items":{"type":"object","required":["channel","token","expiresAt"],"properties":{"channel":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"conversationId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"onlineStateUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Null for normal conversation subscriptions. Present only when a grant also doubles as an online-state subscription target."}},"additionalProperties":false}},"onlineStateSubscriptions":{"description":"Per-user Centrifugo grants for approximate online-state event tracking. Each grant subscribes to a presence-only channel for a visible roster user and never grants another user's personal inbox channel. Use these events to update roster state; do not poll.","type":"array","items":{"type":"object","required":["channel","token","expiresAt"],"properties":{"channel":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"conversationId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"onlineStateUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The concrete user whose presence-only channel this online-state grant tracks."}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/runtime":{"get":{"summary":"Get system chat runtime status","tags":["System Chat"],"description":"Return the effective Centrifugo runtime readiness, health endpoint status, and cluster node summary for system chat operations.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["runtimeEnabled","transportConfigured","httpApiConfigured","healthEndpointConfigured","healthStatus","healthHttpStatus","runtimeInfoStatus","runtimeInfoError","nodeCount","activeChannels","activeClients","activeUsers","version","reconnectTelemetry","publishTelemetry"],"properties":{"runtimeEnabled":{"type":"boolean"},"transportConfigured":{"type":"boolean"},"httpApiConfigured":{"type":"boolean"},"healthEndpointConfigured":{"type":"boolean"},"healthStatus":{"type":"string","enum":["healthy","degraded","unavailable","not_configured"]},"healthHttpStatus":{"anyOf":[{"type":"integer","minimum":100,"maximum":599},{"type":"null"}]},"runtimeInfoStatus":{"type":"string","enum":["available","unavailable"]},"runtimeInfoError":{"anyOf":[{"type":"string"},{"type":"null"}]},"nodeCount":{"type":"integer","minimum":0},"activeChannels":{"type":"integer","minimum":0},"activeClients":{"type":"integer","minimum":0},"activeUsers":{"type":"integer","minimum":0},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"reconnectTelemetry":{"type":"object","required":["windowMinutes","reconnectSessionCount","subscriptionBatchCount","lastReconnectAt","lastSubscriptionBatchAt"],"properties":{"windowMinutes":{"type":"integer","minimum":1},"reconnectSessionCount":{"type":"integer","minimum":0},"subscriptionBatchCount":{"type":"integer","minimum":0},"lastReconnectAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastSubscriptionBatchAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"publishTelemetry":{"type":"object","required":["windowMinutes","publishCount","publishFailureCount","averageLatencyMs","p95LatencyMs","lastPublishAt","lastPublishFailureAt"],"properties":{"windowMinutes":{"type":"integer","minimum":1},"publishCount":{"type":"integer","minimum":0},"publishFailureCount":{"type":"integer","minimum":0},"averageLatencyMs":{"type":"integer","minimum":0},"p95LatencyMs":{"type":"integer","minimum":0},"lastPublishAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastPublishFailureAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/scaling":{"get":{"summary":"Get system chat scaling status","tags":["System Chat"],"description":"Return Centrifugo node counts, active cluster totals, and token TTL settings used for system-level chat scaling decisions.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["nodeCount","activeChannels","activeClients","activeUsers","connectionTokenTtlSeconds","subscriptionTokenTtlSeconds","scalingMode","useTls"],"properties":{"nodeCount":{"type":"integer","minimum":0},"activeChannels":{"type":"integer","minimum":0},"activeClients":{"type":"integer","minimum":0},"activeUsers":{"type":"integer","minimum":0},"connectionTokenTtlSeconds":{"type":"integer","minimum":0},"subscriptionTokenTtlSeconds":{"type":"integer","minimum":0},"scalingMode":{"type":"string","enum":["single-node","clustered","unavailable"]},"useTls":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/infrastructure":{"get":{"summary":"Get system chat infrastructure summary","tags":["System Chat"],"description":"Return the configured chat transport, HTTP API, and health endpoint infrastructure values visible to system administrators.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["runtimeEnabled","transportConfigured","httpApiConfigured","healthEndpointConfigured","wsEndpoint","httpApiEndpoint","internalHealthEndpoint","tokenIssuer","tokenAudience","useTls"],"properties":{"runtimeEnabled":{"type":"boolean"},"transportConfigured":{"type":"boolean"},"httpApiConfigured":{"type":"boolean"},"healthEndpointConfigured":{"type":"boolean"},"wsEndpoint":{"anyOf":[{"type":"string"},{"type":"null"}]},"httpApiEndpoint":{"anyOf":[{"type":"string"},{"type":"null"}]},"internalHealthEndpoint":{"anyOf":[{"type":"string"},{"type":"null"}]},"tokenIssuer":{"type":"string"},"tokenAudience":{"type":"string"},"useTls":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/policies":{"get":{"summary":"Get system chat policy summary","tags":["System Chat"],"description":"Return effective system-wide chat token TTL policy plus tenant override counts for routing and quiet-hours behavior.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["runtimeEnabled","connectionTokenTtlSeconds","subscriptionTokenTtlSeconds","tenantOverridesConfigured","managedRoutingTenants","disabledRoutingTenants","quietHoursEnabledTenants"],"properties":{"runtimeEnabled":{"type":"boolean"},"connectionTokenTtlSeconds":{"type":"integer","minimum":0},"subscriptionTokenTtlSeconds":{"type":"integer","minimum":0},"tenantOverridesConfigured":{"type":"integer","minimum":0},"managedRoutingTenants":{"type":"integer","minimum":0},"disabledRoutingTenants":{"type":"integer","minimum":0},"quietHoursEnabledTenants":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/metrics":{"get":{"summary":"Get system chat metrics","tags":["System Chat"],"description":"Return cross-tenant conversation, message, delivery, and active runtime metrics for system chat diagnostics.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["conversationCount","participantCount","messagesLast24h","messagesLast7d","activeUsers","activeChannels","activePushDevices","queuedDeliveries","failedDeliveries","deliveredDeliveries","messageRateLimit","reconnectTelemetry","publishTelemetry"],"properties":{"conversationCount":{"type":"integer","minimum":0},"participantCount":{"type":"integer","minimum":0},"messagesLast24h":{"type":"integer","minimum":0},"messagesLast7d":{"type":"integer","minimum":0},"activeUsers":{"type":"integer","minimum":0},"activeChannels":{"type":"integer","minimum":0},"activePushDevices":{"type":"integer","minimum":0},"queuedDeliveries":{"type":"integer","minimum":0},"failedDeliveries":{"type":"integer","minimum":0},"deliveredDeliveries":{"type":"integer","minimum":0},"messageRateLimit":{"type":"object","required":["tenantsTracked","activeSends","sendsInWindow","rateLimitedCount","highestUtilizationPercent","tenantsNearLimit","lastMessageAt","lastRateLimitedAt"],"properties":{"tenantsTracked":{"type":"integer","minimum":0},"activeSends":{"type":"integer","minimum":0},"sendsInWindow":{"type":"integer","minimum":0},"rateLimitedCount":{"type":"integer","minimum":0},"highestUtilizationPercent":{"type":"integer","minimum":0,"maximum":100},"tenantsNearLimit":{"type":"integer","minimum":0},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastRateLimitedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"reconnectTelemetry":{"type":"object","required":["windowMinutes","reconnectSessionCount","subscriptionBatchCount","lastReconnectAt","lastSubscriptionBatchAt"],"properties":{"windowMinutes":{"type":"integer","minimum":1},"reconnectSessionCount":{"type":"integer","minimum":0},"subscriptionBatchCount":{"type":"integer","minimum":0},"lastReconnectAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastSubscriptionBatchAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"publishTelemetry":{"type":"object","required":["windowMinutes","publishCount","publishFailureCount","averageLatencyMs","p95LatencyMs","lastPublishAt","lastPublishFailureAt"],"properties":{"windowMinutes":{"type":"integer","minimum":1},"publishCount":{"type":"integer","minimum":0},"publishFailureCount":{"type":"integer","minimum":0},"averageLatencyMs":{"type":"integer","minimum":0},"p95LatencyMs":{"type":"integer","minimum":0},"lastPublishAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastPublishFailureAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/push-runtime":{"get":{"summary":"Get system chat push runtime summary","tags":["System Chat"],"description":"Return cross-tenant push-device and push-delivery runtime diagnostics for system chat operations.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["activeDeviceCount","invalidDeviceCount","retiredDeviceCount","queuedDeliveryCount","failedDeliveryCount","suppressedDeliveryCount","deliveredDeliveryCount","lastQueuedDeliveryAt","lastFailedDeliveryAt"],"properties":{"activeDeviceCount":{"type":"integer","minimum":0},"invalidDeviceCount":{"type":"integer","minimum":0},"retiredDeviceCount":{"type":"integer","minimum":0},"queuedDeliveryCount":{"type":"integer","minimum":0},"failedDeliveryCount":{"type":"integer","minimum":0},"suppressedDeliveryCount":{"type":"integer","minimum":0},"deliveredDeliveryCount":{"type":"integer","minimum":0},"lastQueuedDeliveryAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastFailedDeliveryAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/push-providers":{"get":{"summary":"Get system chat push provider summary","tags":["System Chat"],"description":"Return the global push-provider governance summary separated from tenant chat policy surfaces.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["providers"],"properties":{"providers":{"type":"array","items":{"type":"object","required":["provider","status","managedRoutingTenants","disabledRoutingTenants","quietHoursEnabledTenants","queuedDeliveryCount","failedDeliveryCount"],"properties":{"provider":{"type":"string","enum":["managed"]},"status":{"type":"string","enum":["healthy","degraded","disabled"]},"managedRoutingTenants":{"type":"integer","minimum":0},"disabledRoutingTenants":{"type":"integer","minimum":0},"quietHoursEnabledTenants":{"type":"integer","minimum":0},"queuedDeliveryCount":{"type":"integer","minimum":0},"failedDeliveryCount":{"type":"integer","minimum":0}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/push-deliveries":{"get":{"summary":"List system chat push deliveries","tags":["System Chat"],"description":"Return the cross-tenant push-delivery drill-down view with derived failure classification for system production support.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","enum":["queued","sending","sent","delivered","suppressed","failed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["none","suppressed","invalid-device","rate-limited","provider-auth","routing","transient","unknown"]},"in":"query","name":"failureClass","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","tenantId","conversationId","recipientUserId","provider","status","failureClass","errorCode","errorMessage","suppressionReason","attemptCount","createdAt","sentAt","deliveredAt"],"properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"recipientUserId":{"type":"string","format":"uuid"},"provider":{"type":"string"},"status":{"type":"string","enum":["queued","sending","sent","delivered","suppressed","failed"]},"failureClass":{"type":"string","enum":["none","suppressed","invalid-device","rate-limited","provider-auth","routing","transient","unknown"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"suppressionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"attemptCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/certificates":{"get":{"summary":"Get system chat certificate inventory","tags":["System Chat"],"description":"Return the shared certificate inventory and runtime binding status used by the Centrifugo Chat platform surfaces.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["provider","runtimeBindings","certificates","summary"],"properties":{"provider":{"type":"string","enum":["letsencrypt","self-signed","none","aws-acm","kubernetes-cert-manager"]},"runtimeBindings":{"type":"array","items":{"type":"object","required":["binding","endpoint","host","matchingDomainId","status"],"properties":{"binding":{"type":"string","enum":["chat-websocket","chat-http-api","chat-health"]},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}]},"host":{"anyOf":[{"type":"string"},{"type":"null"}]},"matchingDomainId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["matched","unmatched","unconfigured"]}},"additionalProperties":false}},"certificates":{"type":"array","items":{"type":"object","required":["domainId","tenantId","domain","domainStatus","sslStatus","issuedAt","expiresAt","bindings"],"properties":{"domainId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"domain":{"type":"string"},"domainStatus":{"type":"string","enum":["pending","verifying","verified","failed","expired"]},"sslStatus":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"]},"issuedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"bindings":{"type":"array","items":{"type":"string","enum":["chat-websocket","chat-http-api","chat-health"]}}},"additionalProperties":false}},"summary":{"type":"object","required":["totalCertificates","issuedCertificates","pendingCertificates","expiringCertificates","expiredCertificates","failedCertificates"],"properties":{"totalCertificates":{"type":"integer","minimum":0},"issuedCertificates":{"type":"integer","minimum":0},"pendingCertificates":{"type":"integer","minimum":0},"expiringCertificates":{"type":"integer","minimum":0},"expiredCertificates":{"type":"integer","minimum":0},"failedCertificates":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/chat/certificates/renew":{"post":{"summary":"Trigger system chat certificate renewal check","tags":["System Chat"],"description":"Run the shared certificate renewal and expiring-notification checks used by the Centrifugo Chat certificate operations surface.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["provider","renewedCertificates","expiringNotifications","triggeredAt"],"properties":{"provider":{"type":"string","enum":["letsencrypt","self-signed","none","aws-acm","kubernetes-cert-manager"]},"renewedCertificates":{"type":"integer","minimum":0},"expiringNotifications":{"type":"integer","minimum":0},"triggeredAt":{"type":"string","format":"date-time"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/devices":{"get":{"summary":"List notification devices","tags":["Notifications"],"description":"List the current user notification devices registered in the active tenant.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","deviceUid","platform","pushProvider","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"deviceUid":{"type":"string"},"platform":{"type":"string","enum":["web","ios","android"]},"pushProvider":{"type":"string","enum":["webpush","apns","fcm"]},"status":{"type":"string","enum":["active","invalid","retired"]},"capabilities":{"type":"object","additionalProperties":true},"appVersion":{"anyOf":[{"type":"string"},{"type":"null"}]},"osVersion":{"anyOf":[{"type":"string"},{"type":"null"}]},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastSeenAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Register notification device","tags":["Notifications"],"description":"Create or refresh the current user notification device binding in the active tenant. For pushProvider=\"webpush\", pushToken must be JSON.stringify(subscription.toJSON()) and include endpoint plus keys.p256dh and keys.auth. Re-registering with the same deviceUid supersedes the previous token.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["deviceUid","platform","pushProvider","pushToken"],"properties":{"deviceUid":{"type":"string","minLength":1,"maxLength":255},"platform":{"type":"string","enum":["web","ios","android"]},"pushProvider":{"type":"string","enum":["webpush","apns","fcm"]},"pushToken":{"type":"string","minLength":1,"maxLength":4096,"description":"Web Push subscriptions must use JSON.stringify(subscription.toJSON()) and include endpoint plus keys (p256dh, auth)."},"capabilities":{"type":"object","additionalProperties":true},"appVersion":{"type":"string","maxLength":100},"osVersion":{"type":"string","maxLength":100},"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":100}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","deviceUid","platform","pushProvider","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"deviceUid":{"type":"string"},"platform":{"type":"string","enum":["web","ios","android"]},"pushProvider":{"type":"string","enum":["webpush","apns","fcm"]},"status":{"type":"string","enum":["active","invalid","retired"]},"capabilities":{"type":"object","additionalProperties":true},"appVersion":{"anyOf":[{"type":"string"},{"type":"null"}]},"osVersion":{"anyOf":[{"type":"string"},{"type":"null"}]},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastSeenAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/devices/webpush-client-config":{"get":{"summary":"Get web push client config","tags":["Notifications"],"description":"Return client-safe Web Push bootstrap values for authenticated browser registration, including whether tenant/runtime webpush is supported and the VAPID public key used to create PushSubscription entries.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["supported","publicKey"],"properties":{"supported":{"type":"boolean"},"publicKey":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/devices/{deviceId}":{"delete":{"summary":"Delete notification device","tags":["Notifications"],"description":"Delete the current user notification device binding in the active tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"deviceId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/preferences":{"get":{"summary":"List notification preferences","tags":["Notifications"],"description":"List the effective tenant-default and user-override preferences for the current user.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","tenantId","scope","category","channel","enabled","quietHours","rules","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"scope":{"type":"string","enum":["tenant_default","user_override"]},"category":{"type":"string"},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"enabled":{"type":"boolean"},"quietHours":{"type":"object","additionalProperties":true},"rules":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update notification preferences","tags":["Notifications"],"description":"Update user-override notification preferences for the current user.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["preferences"],"properties":{"preferences":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["category","channel","enabled"],"properties":{"category":{"type":"string","minLength":1,"maxLength":120},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"enabled":{"type":"boolean"},"quietHours":{"type":"object","additionalProperties":true},"rules":{"type":"object","additionalProperties":true}},"additionalProperties":false}}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","tenantId","scope","category","channel","enabled","quietHours","rules","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"scope":{"type":"string","enum":["tenant_default","user_override"]},"category":{"type":"string"},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"enabled":{"type":"boolean"},"quietHours":{"type":"object","additionalProperties":true},"rules":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/inbox":{"get":{"summary":"List inbox notifications","tags":["Notifications"],"description":"List durable inbox notifications for the current user.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","minLength":1,"maxLength":120},"in":"query","name":"category","required":false},{"schema":{"type":"string","enum":["unread","read","archived","acknowledged","suppressed","expired"]},"in":"query","name":"status","required":false},{"schema":{"type":"boolean"},"in":"query","name":"includeArchived","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["items","nextCursor","unreadCount"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","notificationEventId","tenantId","userId","category","priority","status","title","body","actionPayload","renderPayload","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"notificationEventId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"category":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["unread","read","archived","acknowledged","suppressed","expired"]},"title":{"type":"string"},"body":{"type":"string"},"deeplink":{"anyOf":[{"type":"string"},{"type":"null"}]},"actionPayload":{"type":"object","additionalProperties":true},"renderPayload":{"type":"object","additionalProperties":true},"readAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"acknowledgedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"unreadCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/inbox/{notificationId}":{"get":{"summary":"Get inbox notification","tags":["Notifications"],"description":"Get a single durable inbox notification for the current user.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"notificationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","notificationEventId","tenantId","userId","category","priority","status","title","body","actionPayload","renderPayload","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"notificationEventId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"category":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["unread","read","archived","acknowledged","suppressed","expired"]},"title":{"type":"string"},"body":{"type":"string"},"deeplink":{"anyOf":[{"type":"string"},{"type":"null"}]},"actionPayload":{"type":"object","additionalProperties":true},"renderPayload":{"type":"object","additionalProperties":true},"readAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"acknowledgedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/inbox/{notificationId}/read-state":{"patch":{"summary":"Update notification read state","tags":["Notifications"],"description":"Mark an inbox notification as read or unread.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["read"],"properties":{"read":{"type":"boolean"},"readAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"notificationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","notificationEventId","tenantId","userId","category","priority","status","title","body","actionPayload","renderPayload","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"notificationEventId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"category":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["unread","read","archived","acknowledged","suppressed","expired"]},"title":{"type":"string"},"body":{"type":"string"},"deeplink":{"anyOf":[{"type":"string"},{"type":"null"}]},"actionPayload":{"type":"object","additionalProperties":true},"renderPayload":{"type":"object","additionalProperties":true},"readAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"acknowledgedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/inbox/{notificationId}/archive-state":{"patch":{"summary":"Update notification archive state","tags":["Notifications"],"description":"Archive or restore an inbox notification.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["archived"],"properties":{"archived":{"type":"boolean"},"archivedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"notificationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","notificationEventId","tenantId","userId","category","priority","status","title","body","actionPayload","renderPayload","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"notificationEventId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"category":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["unread","read","archived","acknowledged","suppressed","expired"]},"title":{"type":"string"},"body":{"type":"string"},"deeplink":{"anyOf":[{"type":"string"},{"type":"null"}]},"actionPayload":{"type":"object","additionalProperties":true},"renderPayload":{"type":"object","additionalProperties":true},"readAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"acknowledgedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/inbox/{notificationId}/acknowledge":{"patch":{"summary":"Acknowledge notification","tags":["Notifications"],"description":"Acknowledge an inbox notification that requires explicit user acknowledgment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"acknowledgedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"notificationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","notificationEventId","tenantId","userId","category","priority","status","title","body","actionPayload","renderPayload","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"notificationEventId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"category":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["unread","read","archived","acknowledged","suppressed","expired"]},"title":{"type":"string"},"body":{"type":"string"},"deeplink":{"anyOf":[{"type":"string"},{"type":"null"}]},"actionPayload":{"type":"object","additionalProperties":true},"renderPayload":{"type":"object","additionalProperties":true},"readAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"acknowledgedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/unread-summary":{"get":{"summary":"Get unread summary","tags":["Notifications"],"description":"Return unread counters for the current user as totalUnreadCount plus per-category entries with latestCreatedAt. This endpoint is the canonical badge source for installed PWAs and mobile-web clients.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["totalUnreadCount","categories"],"properties":{"totalUnreadCount":{"type":"integer","minimum":0},"categories":{"type":"array","items":{"type":"object","required":["category","unreadCount","latestCreatedAt"],"properties":{"category":{"type":"string"},"unreadCount":{"type":"integer","minimum":0},"latestCreatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/realtime/session":{"post":{"summary":"Create realtime session","tags":["Notifications"],"description":"Create a bounded realtime notification session token for the current user.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["token","expiresAt","transport"],"properties":{"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"transport":{"type":"object","required":["wsEndpoint","useTls"],"properties":{"wsEndpoint":{"type":"string"},"useTls":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/notifications/realtime/subscriptions":{"post":{"summary":"Create realtime notification subscriptions","tags":["Notifications"],"description":"Create signed realtime channel subscriptions for the requested notification topics.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["topics"],"properties":{"topics":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":255}}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["subscriptions"],"properties":{"subscriptions":{"type":"array","items":{"type":"object","required":["topic","channel","token","expiresAt"],"properties":{"topic":{"type":"string"},"channel":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/notifications/preferences":{"get":{"summary":"List tenant notification preferences","tags":["Admin Notifications"],"description":"List tenant-default or user-override notification preferences from the tenant-admin surface.","parameters":[{"schema":{"type":"string","enum":["tenant_default","user_override"]},"in":"query","name":"scope","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"userId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","tenantId","scope","category","channel","enabled","quietHours","rules","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"scope":{"type":"string","enum":["tenant_default","user_override"]},"category":{"type":"string"},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"enabled":{"type":"boolean"},"quietHours":{"type":"object","additionalProperties":true},"rules":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update tenant notification preferences","tags":["Admin Notifications"],"description":"Update tenant-default or user-override notification preferences from the tenant-admin surface.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["preferences"],"properties":{"preferences":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["category","channel","enabled"],"properties":{"category":{"type":"string","minLength":1,"maxLength":120},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"enabled":{"type":"boolean"},"quietHours":{"type":"object","additionalProperties":true},"rules":{"type":"object","additionalProperties":true}},"additionalProperties":false}},"scope":{"type":"string","enum":["tenant_default","user_override"]},"userId":{"type":"string","format":"uuid"}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","tenantId","scope","category","channel","enabled","quietHours","rules","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"scope":{"type":"string","enum":["tenant_default","user_override"]},"category":{"type":"string"},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"enabled":{"type":"boolean"},"quietHours":{"type":"object","additionalProperties":true},"rules":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/notifications/deliveries":{"get":{"summary":"List tenant notification deliveries","tags":["Admin Notifications"],"description":"List notification deliveries in the current tenant for diagnostics and support.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"in":"query","name":"channel","required":false},{"schema":{"type":"string","enum":["queued","processing","sent","delivered","failed","suppressed","canceled","dead_letter"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","minLength":1,"maxLength":120},"in":"query","name":"provider","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"userId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","userNotificationId","notificationEventId","tenantId","userId","channel","status","attemptCount","scheduledFor","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"userNotificationId":{"type":"string","format":"uuid"},"notificationEventId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}]},"deviceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"status":{"type":"string","enum":["queued","processing","sent","delivered","failed","suppressed","canceled","dead_letter"]},"providerMessageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"attemptCount":{"type":"integer","minimum":0},"lastErrorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastErrorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"scheduledFor":{"type":"string","format":"date-time"},"processedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/notifications/overview":{"get":{"summary":"Get tenant notification overview","tags":["Admin Notifications"],"description":"Return tenant-admin notification delivery counts and backlog summary.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["queuedCount","failedCount","deliveryCountsByChannel","deliveryCountsByStatus"],"properties":{"queuedCount":{"type":"integer","minimum":0},"failedCount":{"type":"integer","minimum":0},"deliveryCountsByChannel":{"type":"array","items":{"type":"object","required":["channel","count"],"properties":{"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"count":{"type":"integer","minimum":0}},"additionalProperties":false}},"deliveryCountsByStatus":{"type":"array","items":{"type":"object","required":["status","count"],"properties":{"status":{"type":"string","enum":["queued","processing","sent","delivered","failed","suppressed","canceled","dead_letter"]},"count":{"type":"integer","minimum":0}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/notifications/providers":{"get":{"summary":"Get notification provider health","tags":["System Notifications"],"description":"Return system notification provider health for push routing diagnostics.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["provider","channel","status","checkedAt"],"properties":{"provider":{"type":"string"},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"status":{"type":"string","enum":["healthy","degraded","down","unknown"]},"checkedAt":{"type":"string","format":"date-time"},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/notifications/providers/test":{"post":{"summary":"Send notification provider test","tags":["System Notifications"],"description":"Run a bounded provider diagnostic send against the configured notification provider surface.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["channel","recipient"],"properties":{"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"recipient":{"type":"string","minLength":1,"maxLength":4096},"tenantId":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":255},"body":{"type":"string","maxLength":4000}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["accepted","channel","provider"],"properties":{"accepted":{"type":"boolean"},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerMessageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/notifications/deliveries/process":{"post":{"summary":"Process notification deliveries","tags":["System Notifications"],"description":"Claim and process a bounded batch of due notification deliveries.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":500},"tenantId":{"type":"string","format":"uuid"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["claimedCount","processedCount","failedCount"],"properties":{"claimedCount":{"type":"integer","minimum":0},"processedCount":{"type":"integer","minimum":0},"failedCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/notifications/runtime":{"get":{"summary":"Get notification runtime","tags":["System Notifications"],"description":"Return system notification queue and runtime health summary.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["queuedOutboxCount","failedOutboxCount","nextScheduledOutboxAt"],"properties":{"queuedOutboxCount":{"type":"integer","minimum":0},"failedOutboxCount":{"type":"integer","minimum":0},"nextScheduledOutboxAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/notifications/deliveries":{"get":{"summary":"List system notification deliveries","tags":["System Notifications"],"description":"List cross-tenant notification deliveries for system-level diagnostics.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"in":"query","name":"channel","required":false},{"schema":{"type":"string","enum":["queued","processing","sent","delivered","failed","suppressed","canceled","dead_letter"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","minLength":1,"maxLength":120},"in":"query","name":"provider","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"userId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","userNotificationId","notificationEventId","tenantId","userId","channel","status","attemptCount","scheduledFor","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"userNotificationId":{"type":"string","format":"uuid"},"notificationEventId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["in_app","push","email","sms","whatsapp","webhook"]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}]},"deviceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"status":{"type":"string","enum":["queued","processing","sent","delivered","failed","suppressed","canceled","dead_letter"]},"providerMessageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"attemptCount":{"type":"integer","minimum":0},"lastErrorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastErrorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"scheduledFor":{"type":"string","format":"date-time"},"processedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/search/":{"get":{"summary":"Run global search","tags":["Search"],"description":"Search across supported entities using the provided full-text query.","responses":{"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/settings/":{"get":{"summary":"List settings","tags":["Settings"],"description":"Retrieve the current backend settings available to the authenticated tenant.","responses":{"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/services/media/{id}/content":{"get":{"summary":"Get media content","tags":["Media"],"description":"Serve signed media content through backend-owned URLs.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"token","required":true},{"schema":{"type":"string","minLength":1},"in":"query","name":"sig","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/services/media/integrity/issues":{"get":{"summary":"List media integrity issues","tags":["Media"],"description":"Find broken media links, missing thumbnails, and stale uploaded avatar references for the current tenant.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"probe_fetchability","required":false},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"probe_limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false},{"schema":{"type":"string","pattern":"^[0-9a-fA-F-]+(,[0-9a-fA-F-]+)*$"},"in":"query","name":"media_ids","required":false,"description":"Comma-separated media file UUIDs to scope integrity checks"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"force_refresh","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["issues","summary"],"properties":{"issues":{"type":"array","items":{"type":"object","required":["issue_key","issue_type","detail","link_id","entity_type","entity_id","entity_name","media_file_id","media_name","media_preview_url","is_main","missing_entity","missing_media","user_id","user_name","current_avatar_url","created_at","consistency_types","repairability"],"properties":{"issue_key":{"type":"string"},"issue_type":{"type":"string","enum":["broken_link","missing_thumbnail","broken_thumbnail","stale_user_avatar","inconsistent_media"]},"detail":{"type":"string"},"link_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"entity_type":{"anyOf":[{"type":"null"},{"type":"string","enum":["tenant","space","resource","user","contact"]}]},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"media_file_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"media_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"media_preview_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"is_main":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"missing_entity":{"type":"boolean"},"missing_media":{"type":"boolean"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"current_avatar_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"consistency_types":{"type":"array","items":{"type":"string","enum":["missing_mapping","path_mismatch","version_mismatch","missing_version_history","bucket_metadata_mismatch","stale_thumbnail_metadata","thumbnail_colocation_drift","storage_object_missing"]}},"repairability":{"type":"string","enum":["repairable","fatal"]}}}},"summary":{"type":"object","required":["total_issues","broken_links","missing_thumbnails","broken_thumbnails","inconsistent_media","missing_entity_links","missing_media_links","stale_user_avatars","consistency"],"properties":{"total_issues":{"type":"number","minimum":0},"broken_links":{"type":"number","minimum":0},"missing_thumbnails":{"type":"number","minimum":0},"broken_thumbnails":{"type":"number","minimum":0},"inconsistent_media":{"type":"number","minimum":0},"missing_entity_links":{"type":"number","minimum":0},"missing_media_links":{"type":"number","minimum":0},"stale_user_avatars":{"type":"number","minimum":0},"consistency":{"type":"object","required":["total_issues","repairable_issues","fatal_issues","missing_mappings","path_mismatches","version_mismatches","missing_version_history","stale_bucket_metadata","stale_thumbnail_metadata","thumbnail_colocation_drift","storage_object_missing"],"properties":{"total_issues":{"type":"number","minimum":0},"repairable_issues":{"type":"number","minimum":0},"fatal_issues":{"type":"number","minimum":0},"missing_mappings":{"type":"number","minimum":0},"path_mismatches":{"type":"number","minimum":0},"version_mismatches":{"type":"number","minimum":0},"missing_version_history":{"type":"number","minimum":0},"stale_bucket_metadata":{"type":"number","minimum":0},"stale_thumbnail_metadata":{"type":"number","minimum":0},"thumbnail_colocation_drift":{"type":"number","minimum":0},"storage_object_missing":{"type":"number","minimum":0}}}}}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/integrity/media/{id}":{"get":{"summary":"Get per-image media consistency","tags":["Media"],"description":"Run storage, links, thumbnails, version, and API consistency checks for one media file.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["mediaFileId","tenantId","checks","summary","thumbnailFiles"],"properties":{"mediaFileId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"checks":{"type":"array","items":{"type":"object","required":["moduleId","title","detail","severity"],"properties":{"moduleId":{"type":"string","enum":["storage","links","thumbnails","version","api"]},"title":{"type":"string","minLength":1},"detail":{"type":"string","minLength":1},"severity":{"type":"string","enum":["success","warning","danger"]},"fixAction":{"anyOf":[{"type":"string","enum":["regenerate-thumbnails"]},{"type":"null"}]}},"additionalProperties":false}},"summary":{"type":"object","required":["totalChecks","failingChecks","repairableChecks","modules"],"properties":{"totalChecks":{"type":"number","minimum":0},"failingChecks":{"type":"number","minimum":0},"repairableChecks":{"type":"number","minimum":0},"modules":{"type":"object","required":["storage","links","thumbnails","version","api"],"properties":{"storage":{"type":"object","required":["totalChecks","failingChecks","repairableChecks"],"properties":{"totalChecks":{"type":"number","minimum":0},"failingChecks":{"type":"number","minimum":0},"repairableChecks":{"type":"number","minimum":0}},"additionalProperties":false},"links":{"type":"object","required":["totalChecks","failingChecks","repairableChecks"],"properties":{"totalChecks":{"type":"number","minimum":0},"failingChecks":{"type":"number","minimum":0},"repairableChecks":{"type":"number","minimum":0}},"additionalProperties":false},"thumbnails":{"type":"object","required":["totalChecks","failingChecks","repairableChecks"],"properties":{"totalChecks":{"type":"number","minimum":0},"failingChecks":{"type":"number","minimum":0},"repairableChecks":{"type":"number","minimum":0}},"additionalProperties":false},"version":{"type":"object","required":["totalChecks","failingChecks","repairableChecks"],"properties":{"totalChecks":{"type":"number","minimum":0},"failingChecks":{"type":"number","minimum":0},"repairableChecks":{"type":"number","minimum":0}},"additionalProperties":false},"api":{"type":"object","required":["totalChecks","failingChecks","repairableChecks"],"properties":{"totalChecks":{"type":"number","minimum":0},"failingChecks":{"type":"number","minimum":0},"repairableChecks":{"type":"number","minimum":0}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"thumbnailFiles":{"type":"array","items":{"type":"object","required":["variantKey","format","storagePath","expected","hasDerivativeRow","existsInStorage","sizeBytes","width","height","status"],"properties":{"variantKey":{"type":"string","minLength":1},"format":{"type":"string","minLength":1},"storagePath":{"type":"string","minLength":1},"expected":{"type":"boolean"},"hasDerivativeRow":{"type":"boolean"},"existsInStorage":{"type":"boolean"},"sizeBytes":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"width":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"height":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}},"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/integrity/issues/repair":{"post":{"summary":"Repair media integrity issue","tags":["Media"],"description":"Repair one media integrity issue by unlinking, relinking, or clearing a stale uploaded avatar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["unlink","relink","clear_user_avatar"]},"link_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["tenant","space","resource","user","contact"]},"entity_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"}},"allOf":[{"if":{"properties":{"action":{"enum":["unlink"]}}},"then":{"required":["link_id"]}},{"if":{"properties":{"action":{"enum":["relink"]}}},"then":{"required":["link_id","entity_type","entity_id"]}},{"if":{"properties":{"action":{"enum":["clear_user_avatar"]}}},"then":{"required":["user_id"]}}],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["action","repaired"],"properties":{"action":{"type":"string","enum":["unlink","relink","clear_user_avatar"]},"repaired":{"type":"boolean"},"link_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/integrity/issues/repair-all":{"post":{"summary":"Repair all safe media integrity issues","tags":["Media"],"description":"Queue a background repair job that removes broken links, clears stale uploaded avatars, and regenerates broken thumbnails for the selected tenant.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["repair_all_safe"]},"tenantId":{"type":"string","format":"uuid"},"probe_limit":{"type":"integer","minimum":1,"maximum":25}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["job_id","job_name","correlation_id","status","tenantId"],"properties":{"job_id":{"type":"string","format":"uuid"},"job_name":{"type":"string"},"correlation_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued"]},"tenantId":{"type":"string","format":"uuid"}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/upload":{"post":{"summary":"Upload media file","tags":["Media"],"description":"Upload media file with multipart/form-data","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/":{"get":{"summary":"List media files","tags":["Media"],"description":"Retrieve paginated media files for the tenant with optional filtering by file type.","parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"in":"query","name":"file_type","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"total":{"type":"number"}},"required":["data","total"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}":{"get":{"summary":"Get media file details","tags":["Media"],"description":"Retrieve a specific media file together with its stored metadata. Use GET /api/v1/services/media/:id/version for client cache-version checks.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"patch":{"summary":"Update media filename","tags":["Media"],"description":"Update the display filename used by media details and file browser search without moving the stored object.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["original_filename"],"properties":{"original_filename":{"type":"string","minLength":1,"maxLength":255}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"tags":["Media"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/version":{"get":{"summary":"Get media cache version","tags":["Media"],"description":"Return the canonical cache-version state for client image refresh checks without loading media bytes or derivative URLs. Missing or deleted media returns 404; this endpoint never returns a null version marker.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["mediaFileId","tenantId","version","versionUpdatedAt","isReady","currentVersion","currentVersionReady","currentVersionState","requiredDerivatives","completedDerivatives","pendingDerivatives","failedDerivatives"],"properties":{"mediaFileId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1,"description":"Latest cache-safe version clients should use for image cache refresh checks. Missing or deleted media returns 404 instead of a null version."},"versionUpdatedAt":{"type":"string","format":"date-time"},"isReady":{"type":"boolean","description":"True when the returned version is ready for client cache refresh."},"currentVersion":{"type":"number","minimum":1,"description":"Newest stored media version. This can be ahead of the cache-safe version while derivatives are processing."},"currentVersionReady":{"type":"boolean","description":"True when newest stored version has all required thumbnail derivatives."},"currentVersionState":{"type":"string","enum":["ready","processing","failed"]},"processingVersion":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"requiredDerivatives":{"type":"number","minimum":0},"completedDerivatives":{"type":"number","minimum":0},"pendingDerivatives":{"type":"number","minimum":0},"failedDerivatives":{"type":"number","minimum":0}},"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/versions":{"get":{"summary":"List media file versions","tags":["Media"],"description":"Retrieve upload/version history for diagnostics and management. Use GET /api/v1/services/media/:id/version for client cache refresh checks.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","media_file_id","version","storage_path","public_url","file_size_bytes","mime_type","uploaded_at","uploaded_by","metadata"],"properties":{"id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid","description":"Referenced media file identifier. Use this field, not the link id, to load media manifests and detail records."},"version":{"type":"number","minimum":1},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"file_size_bytes":{"type":"number","minimum":0},"mime_type":{"type":"string"},"uploaded_at":{"type":"string","format":"date-time"},"uploaded_by":{"type":"string","format":"uuid"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}},"additionalProperties":false}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]}},"additionalProperties":true,"description":"File metadata (EXIF, dimensions, crop intent, etc.)"}}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/crop-intent":{"patch":{"summary":"Update crop intent for the current media version","tags":["Media"],"description":"Persist crop intent, invalidate current derivatives, and trigger re-rendering for current-version media outputs.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["crop_intent"],"properties":{"crop_intent":{"anyOf":[{"type":"object","properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/geo-tag":{"post":{"tags":["Media"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/thumbnails/regenerate":{"post":{"tags":["Media"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number","minimum":1}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"media_file_id":{"type":"string","format":"uuid","description":"Media file identifier for id-addressable manifest refresh operations."},"version":{"type":"number","minimum":1},"previous_version":{"type":"number","minimum":0,"description":"Version that was current before regeneration promoted a new version (cache-busting)."},"thumbnails":{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the selected version."}},"required":["media_file_id","version","thumbnails","thumbnails_ready"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/thumbnails":{"get":{"summary":"Get media thumbnails","tags":["Media"],"description":"Retrieve generated thumbnail URLs for a specific media file version or its current version.","parameters":[{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"version","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"media_file_id":{"type":"string","format":"uuid","description":"Media file identifier for id-addressable manifest refresh operations."},"version":{"type":"number","minimum":1},"previous_version":{"type":"number","minimum":0,"description":"Version that was current before regeneration promoted a new version (cache-busting)."},"thumbnails":{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the selected version."}},"required":["media_file_id","version","thumbnails","thumbnails_ready"],"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/derivative":{"get":{"summary":"Select media derivative delivery URL","tags":["Media"],"description":"Return a signed URL for the requested image derivative selector.","parameters":[{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"version","required":false},{"schema":{"type":"string","enum":["derivative"]},"in":"query","name":"source","required":false},{"schema":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"in":"query","name":"size","required":false},{"schema":{"type":"string","enum":["jpeg","webp","avif"]},"in":"query","name":"format","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["media_file_id","version","requested","selected","repairQueued"],"properties":{"media_file_id":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"requested":{"type":"object","required":["source","size","format"],"properties":{"source":{"type":"string","enum":["derivative"]},"size":{"anyOf":[{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},{"type":"null"}]},"format":{"anyOf":[{"type":"string","enum":["jpeg","webp","avif"]},{"type":"null"}]}},"additionalProperties":false},"selected":{"anyOf":[{"type":"object","required":["source","url","fallbackReason"],"properties":{"source":{"type":"string","enum":["derivative"]},"url":{"type":"string","format":"uri"},"fallbackReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"derivative":{"anyOf":[{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]},"repairQueued":{"type":"boolean"},"repairStatus":{"anyOf":[{"type":"string","enum":["queued","deferred"]},{"type":"null"}]},"repairReason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/derivatives":{"get":{"summary":"List media image derivatives","tags":["Media"],"description":"List generated image derivative and thumbnail records for inspection and client selection.","parameters":[{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"version","required":false},{"schema":{"type":"string","enum":["thumbnail","optimized"]},"in":"query","name":"kind","required":false},{"schema":{"type":"string","enum":["pending","processing","completed","failed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"total":{"type":"number","minimum":0}},"required":["data","total"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/{id}/links":{"get":{"summary":"List media file links","tags":["Media"],"description":"Get all entities linked to this media file (reverse lookup)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["links","total"],"properties":{"links":{"type":"array","items":{"type":"object","required":["id","entity_type","entity_id","entity_name","is_main","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Link ID"},"entity_type":{"type":"string","enum":["user","space","resource","contact","tenant"],"description":"Type of entity linked to this media"},"entity_id":{"type":"string","format":"uuid","description":"ID of the linked entity"},"entity_name":{"type":"string","description":"Display name of the linked entity"},"is_main":{"type":"boolean","description":"Whether this is the main/profile image for the entity"},"created_at":{"type":"string","format":"date-time","description":"When the link was created"}}},"description":"List of entities linked to this media file"},"total":{"type":"number","minimum":0,"description":"Total number of linked entities"}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/entity/{entityType}/{entityId}/media":{"post":{"tags":["Media"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["media_file_id"],"properties":{"media_file_id":{"type":"string","format":"uuid"},"is_main":{"type":"boolean"},"sort_order":{"type":"number","minimum":0},"public_display":{"type":"boolean"},"display_from":{"type":"string","format":"date-time"},"display_until":{"type":"string","format":"date-time"},"caption":{"type":"string","maxLength":1000}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","enum":["tenant","space","resource","user","contact"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.","required":["link_id","tenantId","entity_type","entity_id","media_file_id","is_main","sort_order","public_display","created_at","created_by","media"],"properties":{"link_id":{"type":"string","format":"uuid","description":"Entity-media link identifier. This is not the referenced media file id."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"entity_type":{"type":"string","enum":["tenant","space","resource","user","contact"]},"entity_id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid","description":"Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_display":{"type":"boolean"},"display_from":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"display_until":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"caption":{"anyOf":[{"type":"null"},{"type":"string","maxLength":1000}]},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"media":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"get":{"summary":"List entity media","tags":["Media"],"description":"Retrieve media linked to a specific entity with optional private-media filtering.","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"include_private","required":false},{"schema":{"type":"string","enum":["tenant","space","resource","user","contact"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.","required":["link_id","tenantId","entity_type","entity_id","media_file_id","is_main","sort_order","public_display","created_at","created_by","media"],"properties":{"link_id":{"type":"string","format":"uuid","description":"Entity-media link identifier. This is not the referenced media file id."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"entity_type":{"type":"string","enum":["tenant","space","resource","user","contact"]},"entity_id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid","description":"Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_display":{"type":"boolean"},"display_from":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"display_until":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"caption":{"anyOf":[{"type":"null"},{"type":"string","maxLength":1000}]},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"media":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/entity/{entityType}/{entityId}/media/main":{"get":{"summary":"Get main entity media","tags":["Media"],"description":"Retrieve the primary media item linked to a specific entity.","parameters":[{"schema":{"type":"string","enum":["tenant","space","resource","user","contact"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","description":"Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.","required":["link_id","tenantId","entity_type","entity_id","media_file_id","is_main","sort_order","public_display","created_at","created_by","media"],"properties":{"link_id":{"type":"string","format":"uuid","description":"Entity-media link identifier. This is not the referenced media file id."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"entity_type":{"type":"string","enum":["tenant","space","resource","user","contact"]},"entity_id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid","description":"Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_display":{"type":"boolean"},"display_from":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"display_until":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"caption":{"anyOf":[{"type":"null"},{"type":"string","maxLength":1000}]},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"media":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}]}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/entity/{entityType}/{entityId}/media/{linkId}":{"put":{"tags":["Media"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"is_main":{"type":"boolean"},"sort_order":{"type":"number","minimum":0},"public_display":{"type":"boolean"},"display_from":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"display_until":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"caption":{"anyOf":[{"type":"null"},{"type":"string","maxLength":1000}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","enum":["tenant","space","resource","user","contact"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"linkId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.","required":["link_id","tenantId","entity_type","entity_id","media_file_id","is_main","sort_order","public_display","created_at","created_by","media"],"properties":{"link_id":{"type":"string","format":"uuid","description":"Entity-media link identifier. This is not the referenced media file id."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"entity_type":{"type":"string","enum":["tenant","space","resource","user","contact"]},"entity_id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid","description":"Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_display":{"type":"boolean"},"display_from":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"display_until":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"caption":{"anyOf":[{"type":"null"},{"type":"string","maxLength":1000}]},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"media":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"tags":["Media"],"parameters":[{"schema":{"type":"string","enum":["tenant","space","resource","user","contact"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"linkId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/entity/{entityType}/{entityId}/media/{linkId}/main":{"patch":{"tags":["Media"],"parameters":[{"schema":{"type":"string","enum":["tenant","space","resource","user","contact"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"linkId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.","required":["link_id","tenantId","entity_type","entity_id","media_file_id","is_main","sort_order","public_display","created_at","created_by","media"],"properties":{"link_id":{"type":"string","format":"uuid","description":"Entity-media link identifier. This is not the referenced media file id."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"entity_type":{"type":"string","enum":["tenant","space","resource","user","contact"]},"entity_id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid","description":"Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_display":{"type":"boolean"},"display_from":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"display_until":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"caption":{"anyOf":[{"type":"null"},{"type":"string","maxLength":1000}]},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"media":{"type":"object","description":"Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.","required":["id","tenantId","user_id","file_type","mime_type","file_size_bytes","storage_path","public_url","current_version","original_filename","create_thumbnails","has_thumbnails","thumbnails_ready","has_webp_thumbnails","exif_stripped","metadata","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"user_id":{"type":"string","format":"uuid"},"file_type":{"type":"string","enum":["avatar","profile_picture","document","image","video","other"]},"mime_type":{"type":"string"},"file_size_bytes":{"type":"number","minimum":0},"storage_path":{"type":"string"},"public_url":{"type":"string","format":"uri"},"current_version":{"type":"number","minimum":1,"description":"Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."},"original_filename":{"type":"string","description":"Original filename for display"},"create_thumbnails":{"type":"boolean","description":"Whether to generate thumbnails (user preference)"},"has_thumbnails":{"type":"boolean","description":"Whether thumbnails were successfully generated"},"thumbnails_ready":{"type":"array","items":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"description":"Canonical thumbnail sizes with at least one completed derivative for the current version."},"has_webp_thumbnails":{"type":"boolean","description":"Whether WebP thumbnail derivatives exist for the current version"},"parent_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Reference to previous version for version history"},"geo_location":{"anyOf":[{"type":"null"},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}]},"exif_stripped":{"type":"boolean"},"metadata":{"type":"object","properties":{"original_filename":{"type":"string"},"dimensions":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}]},"image_properties":{"anyOf":[{"type":"null"},{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"orientation":{"type":"number"},"density":{"type":"number"},"format":{"type":"string"},"space":{"type":"string"},"channels":{"type":"number"},"hasAlpha":{"type":"boolean"}},"additionalProperties":false}]},"date_taken":{"type":"string","format":"date-time"},"thumbnails":{"anyOf":[{"type":"null"},{"type":"object","properties":{"xxs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xs":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"sm":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"md":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"lg":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false},"xl":{"type":"object","properties":{"jpeg":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"webp":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true},"avif":{"type":"object","required":["format","mimeType","url","width","height","aspectRatio","sizeBytes","status"],"properties":{"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1,"description":"Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"cropMetadata":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["pending","processing","completed","failed"]}},"additionalProperties":true}},"additionalProperties":false}}}]},"image_derivatives":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","description":"Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.","required":["id","tenantId","mediaFileId","version","targetId","kind","variantKey","format","mimeType","storagePath","width","height","aspectRatio","sizeBytes","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."},"mediaFileId":{"type":"string","format":"uuid"},"version":{"type":"number","minimum":1},"targetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["thumbnail","optimized"]},"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"format":{"type":"string","enum":["jpeg","webp","avif"]},"mimeType":{"type":"string","enum":["image/jpeg","image/webp","image/avif"]},"storagePath":{"type":"string"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1},"aspectRatio":{"type":"number","minimum":0},"sizeBytes":{"type":"number","minimum":1},"quality":{"anyOf":[{"type":"number","minimum":1,"maximum":100},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"targetMet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"cropMetadata":{"type":"object","properties":{"source_orientation":{"type":"string","enum":["portrait","square","landscape"]},"target_aspect":{"type":"number","minimum":0},"crop_intent":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"requested_fit":{"type":"string","enum":["inside","cover","contain"]},"blend_applied":{"type":"boolean"},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"width":{"type":"number","minimum":1},"height":{"type":"number","minimum":1}},"required":["x","y","width","height"],"additionalProperties":false},"requested_crop":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":64},"height":{"type":"number","minimum":64}},"required":["x","y","width","height"],"additionalProperties":false},"padding_px":{"type":"object","properties":{"left":{"type":"number","minimum":0},"top":{"type":"number","minimum":0},"right":{"type":"number","minimum":0},"bottom":{"type":"number","minimum":0}},"required":["left","top","right","bottom"],"additionalProperties":false}},"additionalProperties":true},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}]},"image_optimization":{"anyOf":[{"type":"null"},{"type":"object","required":["source","optimize","formats","variants","maxWidth","maxHeight","targetKilobytes","quality","fit","allowUpscale"],"properties":{"source":{"type":"string","enum":["tenant-defaults","client-request"]},"optimize":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["jpeg","webp","avif"]},"minItems":1},"variants":{"type":"array","items":{"type":"object","required":["variantKey","targetKilobytes"],"properties":{"variantKey":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"targetKilobytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]}},"additionalProperties":false},"minItems":1},"maxWidth":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"maxHeight":{"anyOf":[{"type":"integer","minimum":1,"maximum":2048},{"type":"null"}]},"targetKilobytes":{"anyOf":[{"type":"integer","minimum":1,"maximum":10240},{"type":"null"}]},"quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]},"fit":{"type":"string","enum":["inside","cover","contain"]},"allowUpscale":{"type":"boolean"}},"additionalProperties":false}]},"crop_intent":{"anyOf":[{"type":"null"},{"type":"object","required":["updatedBy","updatedAt"],"properties":{"portrait":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"landscape":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"square":{"type":"object","required":["x1","y1","x2","y2"],"properties":{"x1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"y1":{"type":"number","description":"Crop coordinate. Normalized crop width/height must be at least 64px."},"x2":{"type":"number","description":"Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."},"y2":{"type":"number","description":"Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."}},"additionalProperties":false},"sourceOrientation":{"type":"string","enum":["portrait","square","landscape"]},"updatedBy":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"checksum":{"type":"string"},"caption":{"type":"string"}}},"tags":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Tags associated with this media file"},"categories":{"anyOf":[{"type":"null"},{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"color":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}],"description":"Categories associated with this media file"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/entity/{entityType}/{entityId}/media/reorder":{"put":{"tags":["Media"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["reorder"],"properties":{"reorder":{"type":"array","items":{"type":"object","required":["link_id","sort_order"],"properties":{"link_id":{"type":"string","format":"uuid","description":"Entity-media link identifier used for reorder operations."},"sort_order":{"type":"number","minimum":0}}},"minItems":1}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","enum":["tenant","space","resource","user","contact"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Canonical entity-media link DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.","required":["link_id","tenantId","entity_type","entity_id","media_file_id","is_main","sort_order","public_display","created_at","created_by"],"properties":{"link_id":{"type":"string","format":"uuid","description":"Entity-media link identifier. This is not the referenced media file id."},"tenantId":{"type":"string","format":"uuid","description":"Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."},"entity_type":{"type":"string","enum":["tenant","space","resource","user","contact"]},"entity_id":{"type":"string","format":"uuid"},"media_file_id":{"type":"string","format":"uuid","description":"Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."},"is_main":{"type":"boolean"},"sort_order":{"type":"number"},"public_display":{"type":"boolean"},"display_from":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"display_until":{"anyOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"caption":{"anyOf":[{"type":"null"},{"type":"string","maxLength":1000}]},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"}}}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/media/settings/image-optimization":{"get":{"summary":"Get tenant image optimization settings","tags":["Media Settings"],"description":"Return tenant-scoped automatic image optimization settings for upload defaults and client override policy.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["tenantId","enabled","defaultFormats","avifEnabled","allowClientOverrides","variants","entityDefaults","cropFill"],"properties":{"tenantId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"defaultFormats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}},"avifEnabled":{"type":"boolean"},"allowClientOverrides":{"type":"boolean"},"variants":{"type":"object","required":["xxs","xs","sm","md","lg","xl"],"properties":{"xxs":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"xs":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"sm":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"md":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"lg":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"xl":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false}},"additionalProperties":false},"entityDefaults":{"type":"object","required":["resource","space","user"],"properties":{"resource":{"type":"object","required":["publicUrlVariant","thumbnailUrlVariant"],"properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false},"space":{"type":"object","required":["publicUrlVariant","thumbnailUrlVariant"],"properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false},"user":{"type":"object","required":["publicUrlVariant","thumbnailUrlVariant"],"properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false}},"additionalProperties":false},"cropFill":{"type":"object","required":["mode","colors"],"properties":{"mode":{"type":"string","enum":["blur","color"]},"colors":{"type":"object","required":["jpeg","webp","avif"],"properties":{"jpeg":{"type":"string","minLength":1},"webp":{"type":"string","minLength":1},"avif":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"patch":{"summary":"Update tenant image optimization settings","tags":["Media Settings"],"description":"Update tenant-scoped automatic image optimization settings and clear the tenant media config cache.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"enabled":{"type":"boolean"},"defaultFormats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}},"avifEnabled":{"type":"boolean"},"allowClientOverrides":{"type":"boolean"},"variants":{"type":"object","properties":{"xxs":{"type":"object","properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"xs":{"type":"object","properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"sm":{"type":"object","properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"md":{"type":"object","properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"lg":{"type":"object","properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"xl":{"type":"object","properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false}},"additionalProperties":false},"entityDefaults":{"type":"object","properties":{"resource":{"type":"object","properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false},"space":{"type":"object","properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false},"user":{"type":"object","properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false}},"additionalProperties":false},"cropFill":{"type":"object","minProperties":1,"properties":{"mode":{"type":"string","enum":["blur","color"]},"colors":{"type":"object","minProperties":1,"properties":{"jpeg":{"type":"string","minLength":1},"webp":{"type":"string","minLength":1},"avif":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["tenantId","enabled","defaultFormats","avifEnabled","allowClientOverrides","variants","entityDefaults","cropFill"],"properties":{"tenantId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"defaultFormats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}},"avifEnabled":{"type":"boolean"},"allowClientOverrides":{"type":"boolean"},"variants":{"type":"object","required":["xxs","xs","sm","md","lg","xl"],"properties":{"xxs":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"xs":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"sm":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"md":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"lg":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false},"xl":{"type":"object","required":["width","height","targetKilobytes","aspectPolicy","formats"],"properties":{"width":{"type":"integer","minimum":1,"maximum":2048},"height":{"type":"integer","minimum":1,"maximum":2048},"targetKilobytes":{"type":"integer","minimum":1,"maximum":1536},"aspectPolicy":{"type":"string","enum":["source","square","landscape","portrait","adaptive"]},"formats":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["jpeg","webp","avif"]}}},"additionalProperties":false}},"additionalProperties":false},"entityDefaults":{"type":"object","required":["resource","space","user"],"properties":{"resource":{"type":"object","required":["publicUrlVariant","thumbnailUrlVariant"],"properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false},"space":{"type":"object","required":["publicUrlVariant","thumbnailUrlVariant"],"properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false},"user":{"type":"object","required":["publicUrlVariant","thumbnailUrlVariant"],"properties":{"publicUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]},"thumbnailUrlVariant":{"type":"string","enum":["xxs","xs","sm","md","lg","xl"]}},"additionalProperties":false}},"additionalProperties":false},"cropFill":{"type":"object","required":["mode","colors"],"properties":{"mode":{"type":"string","enum":["blur","color"]},"colors":{"type":"object","required":["jpeg","webp","avif"],"properties":{"jpeg":{"type":"string","minLength":1},"webp":{"type":"string","minLength":1},"avif":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/send":{"post":{"summary":"Send message","tags":["Messaging"],"description":"Queue a message for delivery via email, SMS, WhatsApp, or webhook","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms","whatsapp","webhook"],"description":"Delivery channel"},"recipient_email":{"type":"string","format":"email","nullable":true},"recipient_phone":{"type":"string","nullable":true},"recipient_user_id":{"type":"string","format":"uuid","nullable":true},"template_id":{"type":"string","format":"uuid","nullable":true},"template_name":{"type":"string","nullable":true},"subject":{"type":"string","nullable":true},"content":{"type":"string","nullable":true},"variables":{"type":"object","additionalProperties":true,"nullable":true}},"required":["channel"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"channel":{"type":"string"},"created_at":{"type":"string"}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/{id}/status":{"get":{"summary":"Get message status","tags":["Messaging"],"description":"Get delivery status and tracking info for a specific message","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"channel":{"type":"string"},"retry_count":{"type":"number"},"max_retries":{"type":"number"},"next_retry_at":{"type":"string","nullable":true},"last_error":{"type":"string","nullable":true},"provider_message_id":{"type":"string","nullable":true},"provider_response":{"type":"object","nullable":true,"additionalProperties":true},"sent_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"opened_at":{"type":"string","nullable":true},"clicked_at":{"type":"string","nullable":true},"bounced_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/{id}/provider-logs":{"get":{"summary":"Get provider logs","tags":["Messaging"],"description":"Get provider interaction logs for a specific message (attempts, errors, responses)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"provider":{"type":"string","description":"Provider name: sendgrid, mail2sms, twilio, webhook"},"channel":{"type":"string","description":"Channel: email, sms, whatsapp, webhook"},"recipient":{"type":"string","nullable":true},"event_type":{"type":"string","enum":["attempt","success","failure","retry","config_error","provider_error"],"description":"Type of provider interaction event"},"attempt_number":{"type":"integer","description":"Retry attempt number"},"success":{"type":"boolean","nullable":true,"description":"Whether the API call succeeded"},"status_code":{"type":"integer","nullable":true,"description":"HTTP status code from provider"},"provider_message_id":{"type":"string","nullable":true,"description":"Message ID returned by provider"},"response_data":{"type":"object","nullable":true,"additionalProperties":true,"description":"Full provider API response for debugging"},"error_message":{"type":"string","nullable":true,"description":"Error message if failed"},"error_details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Detailed error information from provider"},"duration_ms":{"type":"integer","nullable":true,"description":"API call duration in milliseconds"},"created_at":{"type":"string","format":"date-time"}},"required":["id","provider","channel","event_type","attempt_number","created_at"]}}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/{id}/retry":{"post":{"summary":"Retry message","tags":["Messaging"],"description":"Retry a failed or stuck message by resetting it to queued status","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"status":{"type":"string","description":"New message status after action"}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/{id}/cancel":{"post":{"summary":"Cancel message","tags":["Messaging"],"description":"Cancel a pending message (only works for queued messages)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"status":{"type":"string","description":"New message status after action"}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/preview":{"post":{"summary":"Preview message template","tags":["Messaging"],"description":"Preview a rendered message template with variables without sending it","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["template_id","variables"],"properties":{"template_id":{"type":"string","format":"uuid"},"variables":{"type":"object"}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"subject":{"type":"string","nullable":true},"content":{"type":"string"},"variables_used":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/templates":{"get":{"summary":"List message templates","tags":["Messaging"],"description":"List available message templates, optionally filtered by channel and/or language","parameters":[{"schema":{"type":"string","enum":["email","sms","whatsapp","webhook"]},"in":"query","name":"channel","required":false},{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"language","required":false,"description":"Filter by ISO language code (e.g., en, de, fr)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["null","string"]},"channel":{"type":"string"},"version":{"type":"number"},"variables":{"type":"array","items":{"type":"string"}},"language":{"type":"string","description":"ISO language code"},"subject":{"type":["null","string"],"description":"Email subject (for email channel)"},"content":{"type":"string","description":"Template content with {{variables}}"}}}}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"post":{"summary":"Create message template","tags":["Messaging"],"description":"Create a new message template","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","channel","content","variables"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"channel":{"type":"string","enum":["email","sms","whatsapp","webhook"]},"subject":{"type":"string"},"content":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"language":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$","description":"ISO language code (e.g., en, de, fr). Defaults to en."}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["null","string"]},"channel":{"type":"string"},"version":{"type":"number"},"variables":{"type":"array","items":{"type":"string"}},"language":{"type":"string","description":"ISO language code"},"subject":{"type":["null","string"],"description":"Email subject (for email channel)"},"content":{"type":"string","description":"Template content with {{variables}}"}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/stats":{"get":{"summary":"Get messaging statistics","tags":["Messaging"],"description":"Get messaging statistics for the tenant (counts by status)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_messages":{"type":"number"},"queued":{"type":"number"},"sent":{"type":"number"},"delivered":{"type":"number"},"failed":{"type":"number"},"bounced":{"type":"number"}}}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/recent":{"get":{"summary":"List recent messages","tags":["Messaging"],"description":"List recent messages sent by the tenant with optional limit","parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string"},"status":{"type":"string"},"subject":{"type":"string","nullable":true},"recipient_email":{"type":"string","nullable":true},"recipient_phone":{"type":"string","nullable":true},"created_at":{"type":"string"},"sent_at":{"type":"string","nullable":true},"retry_count":{"type":"number"},"max_retries":{"type":"number"},"next_retry_at":{"type":"string","nullable":true},"last_error":{"type":"string","nullable":true},"provider_message_id":{"type":"string","nullable":true},"provider_response":{"type":"object","nullable":true,"additionalProperties":true}}}}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/templates/{id}":{"put":{"summary":"Update message template","tags":["Messaging"],"description":"Update a message template (creates new version)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string"},"subject":{"type":"string"},"content":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["null","string"]},"channel":{"type":"string"},"version":{"type":"number"},"variables":{"type":"array","items":{"type":"string"}},"language":{"type":"string","description":"ISO language code"},"subject":{"type":["null","string"],"description":"Email subject (for email channel)"},"content":{"type":"string","description":"Template content with {{variables}}"}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Delete message template","tags":["Messaging"],"description":"Delete a message template (deactivates all versions)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Template deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/services/messaging/rate-limits":{"get":{"summary":"Get rate limit statistics","tags":["Messaging"],"description":"Get current rate limiting statistics for message sending","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"stats":{"type":"array","items":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["email","sms","whatsapp","webhook"]},"activeSends":{"type":"integer","description":"Currently active concurrent sends"},"sendsInWindow":{"type":"integer","description":"Total sends in current 1-minute window"},"maxConcurrent":{"type":"integer","description":"Maximum allowed concurrent sends"},"maxPerMinute":{"type":"integer","description":"Maximum sends allowed per minute"}},"required":["tenantId","channel","activeSends","sendsInWindow","maxConcurrent","maxPerMinute"]}},"defaultLimits":{"type":"object","properties":{"email":{"type":"object","properties":{"maxConcurrent":{"type":"integer"},"maxPerMinute":{"type":"integer"}}},"sms":{"type":"object","properties":{"maxConcurrent":{"type":"integer"},"maxPerMinute":{"type":"integer"}}},"whatsapp":{"type":"object","properties":{"maxConcurrent":{"type":"integer"},"maxPerMinute":{"type":"integer"}}},"webhook":{"type":"object","properties":{"maxConcurrent":{"type":"integer"},"maxPerMinute":{"type":"integer"}}}}}}}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/rate-limits/config":{"get":{"summary":"Get rate limit configuration","tags":["Messaging"],"description":"Get current rate limit configuration for the tenant","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"config":{"type":"object","properties":{"email":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"sms":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"whatsapp":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"webhook":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]}},"additionalProperties":false},"defaults":{"type":"object","properties":{"email":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"sms":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"whatsapp":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"webhook":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]}},"additionalProperties":false},"isCustom":{"type":"boolean","description":"Whether tenant has custom rate limits configured"}},"required":["config","defaults","isCustom"]}},"required":["data"]}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"put":{"summary":"Update rate limit configuration","tags":["Messaging"],"description":"Update rate limit configuration for the tenant. Supports partial updates.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000}}},"sms":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000}}},"whatsapp":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000}}},"webhook":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000}}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"config":{"type":"object","properties":{"email":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"sms":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"whatsapp":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"webhook":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]}},"additionalProperties":false},"defaults":{"type":"object","properties":{"email":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"sms":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"whatsapp":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]},"webhook":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum concurrent sends (semaphore slots)"},"maxPerMinute":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum sends per minute per tenant"},"cooldownMs":{"type":"integer","minimum":100,"maximum":60000,"description":"Cooldown period in milliseconds when limit is hit"}},"required":["maxConcurrent","maxPerMinute","cooldownMs"]}},"additionalProperties":false},"isCustom":{"type":"boolean","description":"Whether tenant has custom rate limits configured"}},"required":["config","defaults","isCustom"]}},"required":["data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Reset rate limit configuration","tags":["Messaging"],"description":"Reset rate limit configuration to system defaults","responses":{"204":{"description":"Rate limit configuration reset successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/services/messaging/templates/{id}/export":{"get":{"summary":"Export message template","tags":["Messaging"],"description":"Export a single message template as JSON","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["null","string"]},"channel":{"type":"string","enum":["email","sms","whatsapp","webhook"]},"subject":{"type":["null","string"]},"content":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"language":{"type":"string"},"version":{"type":"number"}},"required":["name","channel","content","variables","language","version"]}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/templates/export":{"get":{"summary":"Export message templates","tags":["Messaging"],"description":"Export all message templates for the tenant as JSON bundle","parameters":[{"schema":{"type":"string","enum":["email","sms","whatsapp","webhook"]},"in":"query","name":"channel","required":false,"description":"Filter by channel"},{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"language","required":false,"description":"Filter by language"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"version":{"type":"string","description":"Bundle version (e.g., \"1.0\")"},"exportedAt":{"type":"string","format":"date-time"},"source":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantSlug":{"type":"string"}},"required":["tenantId"]},"templates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["null","string"]},"channel":{"type":"string","enum":["email","sms","whatsapp","webhook"]},"subject":{"type":["null","string"]},"content":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"language":{"type":"string"},"version":{"type":"number"}},"required":["name","channel","content","variables","language","version"]}}},"required":["version","exportedAt","source","templates"]}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/services/messaging/templates/import":{"post":{"summary":"Import message templates","tags":["Messaging"],"description":"Import message templates from JSON. Supports individual templates or bundle format.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"channel":{"type":"string","enum":["email","sms","whatsapp","webhook"]},"subject":{"type":["string","null"]},"content":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"language":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"}},"required":["name","channel","content"]}},"options":{"type":"object","properties":{"mergeStrategy":{"type":"string","enum":["skip","replace","merge"],"default":"skip","description":"How to handle existing templates: skip (keep existing), replace (overwrite), merge (update only empty fields)"},"dryRun":{"type":"boolean","default":false,"description":"If true, validate without saving"}}}},"required":["templates"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"dryRun":{"type":"boolean"},"stats":{"type":"object","properties":{"created":{"type":"number"},"updated":{"type":"number"},"skipped":{"type":"number"},"errors":{"type":"number"}}},"warnings":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","description":"Template index in input array"},"name":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/feedback/rating":{"post":{"summary":"Submit rating","tags":["Feedback"],"description":"Submit a rating for an entity (resource, space, booking, app)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["entityType","entityId","ratingType","value"],"properties":{"entityType":{"type":"string","enum":["app","booking","resource","space"]},"entityId":{"type":"string","format":"uuid"},"ratingType":{"type":"string","enum":["hearts","stars"]},"value":{"type":"number"},"isPublic":{"type":"boolean"}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["app","booking","resource","space"]},"entity_id":{"type":"string","format":"uuid"},"rating_type":{"type":"string","enum":["hearts","stars"]},"value":{"type":"number"},"is_public":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","user_id","entity_type","entity_id","rating_type","value","is_public","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/feedback/rating/{id}":{"put":{"summary":"Update rating","tags":["Feedback"],"description":"Update an existing rating","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"value":{"type":"number"},"isPublic":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["app","booking","resource","space"]},"entity_id":{"type":"string","format":"uuid"},"rating_type":{"type":"string","enum":["hearts","stars"]},"value":{"type":"number"},"is_public":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","user_id","entity_type","entity_id","rating_type","value","is_public","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Delete rating","tags":["Feedback"],"description":"Delete an existing rating (and its reviews)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Rating deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/feedback/review":{"post":{"summary":"Submit review","tags":["Feedback"],"description":"Submit a review linked to a rating","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ratingId","content"],"properties":{"ratingId":{"type":"string","format":"uuid"},"content":{"type":"string","minLength":10,"maxLength":5000},"attachments":{"type":"array","items":{"type":"object","properties":{"media_id":{"type":"string","format":"uuid"},"media_type":{"type":"string","enum":["image","video","document"]},"url":{"type":"string","format":"uri"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["media_id","media_type","url"],"additionalProperties":false}},"isPublic":{"type":"boolean"}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"rating_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"content":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"media_id":{"type":"string","format":"uuid"},"media_type":{"type":"string","enum":["image","video","document"]},"url":{"type":"string","format":"uri"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["media_id","media_type","url"],"additionalProperties":false}},"is_public":{"type":"boolean"},"is_flagged":{"type":"boolean"},"flagged_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"flagged_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"flagged_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","rating_id","user_id","content","attachments","is_public","is_flagged","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/feedback/review/{id}":{"put":{"summary":"Update review","tags":["Feedback"],"description":"Update an existing review","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"content":{"type":"string","minLength":10,"maxLength":5000},"attachments":{"type":"array","items":{"type":"object","properties":{"media_id":{"type":"string","format":"uuid"},"media_type":{"type":"string","enum":["image","video","document"]},"url":{"type":"string","format":"uri"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["media_id","media_type","url"],"additionalProperties":false}},"isPublic":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"rating_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"content":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"media_id":{"type":"string","format":"uuid"},"media_type":{"type":"string","enum":["image","video","document"]},"url":{"type":"string","format":"uri"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["media_id","media_type","url"],"additionalProperties":false}},"is_public":{"type":"boolean"},"is_flagged":{"type":"boolean"},"flagged_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"flagged_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"flagged_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","rating_id","user_id","content","attachments","is_public","is_flagged","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Delete review","tags":["Feedback"],"description":"Delete an existing review","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Review deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/feedback/review/{id}/flag":{"post":{"summary":"Flag review","tags":["Feedback"],"description":"Flag a review for moderation (admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"rating_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"content":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"media_id":{"type":"string","format":"uuid"},"media_type":{"type":"string","enum":["image","video","document"]},"url":{"type":"string","format":"uri"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["media_id","media_type","url"],"additionalProperties":false}},"is_public":{"type":"boolean"},"is_flagged":{"type":"boolean"},"flagged_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"flagged_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"flagged_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","rating_id","user_id","content","attachments","is_public","is_flagged","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/feedback/{entityType}/{entityId}/ratings":{"get":{"summary":"List entity ratings","tags":["Feedback"],"description":"Get all ratings for an entity","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"includePrivate","required":false},{"schema":{"type":"string","enum":["app","booking","resource","space"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["app","booking","resource","space"]},"entity_id":{"type":"string","format":"uuid"},"rating_type":{"type":"string","enum":["hearts","stars"]},"value":{"type":"number"},"is_public":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","user_id","entity_type","entity_id","rating_type","value","is_public","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/feedback/{entityType}/{entityId}/reviews":{"get":{"summary":"List entity reviews","tags":["Feedback"],"description":"Get all reviews for an entity","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"includePrivate","required":false},{"schema":{"type":"number","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["app","booking","resource","space"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"rating_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"content":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"media_id":{"type":"string","format":"uuid"},"media_type":{"type":"string","enum":["image","video","document"]},"url":{"type":"string","format":"uri"},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["media_id","media_type","url"],"additionalProperties":false}},"is_public":{"type":"boolean"},"is_flagged":{"type":"boolean"},"flagged_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"flagged_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"flagged_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","rating_id","user_id","content","attachments","is_public","is_flagged","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/feedback/{entityType}/{entityId}/aggregates":{"get":{"summary":"Get entity rating aggregates","tags":["Feedback"],"description":"Get rating aggregates (average, count, distribution) for an entity","parameters":[{"schema":{"type":"string","enum":["hearts","stars"]},"in":"query","name":"ratingType","required":true},{"schema":{"type":"string","enum":["app","booking","resource","space"]},"in":"path","name":"entityType","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"entityId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity_type":{"type":"string","enum":["app","booking","resource","space"]},"entity_id":{"type":"string","format":"uuid"},"rating_type":{"type":"string","enum":["hearts","stars"]},"total_count":{"type":"number"},"average_rating":{"type":"number"},"distribution":{"type":"object","additionalProperties":{"type":"number"},"description":"Rating value -> count mapping"},"public_count":{"type":"number"},"private_count":{"type":"number"}},"required":["entity_type","entity_id","rating_type","total_count","average_rating","distribution","public_count","private_count"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/":{"get":{"summary":"List calendars","tags":["Calendar"],"description":"Retrieve calendars visible to the current user with optional filtering and pagination.","parameters":[{"schema":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"in":"query","name":"kind","required":false},{"schema":{"type":"string","enum":["private","shared","public_within_tenant"]},"in":"query","name":"visibility","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"linkedUserId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"linkedResourceId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"linkedSpaceId","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"type":"string"},"visibility":{"type":"string","enum":["private","shared","public_within_tenant"]},"policy":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"linkedEntity":{"type":"object","properties":{"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["userId","resourceId","spaceId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","kind","name","timezone","visibility","policy","metadata","typeDefinitionId","linkedEntity","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create calendar","tags":["Calendar"],"description":"Create a calendar and configure its visibility, linkage, and metadata.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"timezone":{"type":"string","minLength":1,"maxLength":64},"visibility":{"type":"string","enum":["private","shared","public_within_tenant"]},"policy":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"type":"string","format":"uuid"},"linkedUserId":{"type":"string","format":"uuid"},"linkedResourceId":{"type":"string","format":"uuid"},"linkedSpaceId":{"type":"string","format":"uuid"}},"required":["kind","name","timezone"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"type":"string"},"visibility":{"type":"string","enum":["private","shared","public_within_tenant"]},"policy":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"linkedEntity":{"type":"object","properties":{"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["userId","resourceId","spaceId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","kind","name","timezone","visibility","policy","metadata","typeDefinitionId","linkedEntity","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/window":{"get":{"summary":"List visible calendar events in a bounded window","tags":["Calendar"],"description":"Retrieve visible calendar events within a bounded time window for the selected calendars.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startsAt","required":true},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endsAt","required":true},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"calendarIds","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeCancelled","required":false},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"location":{"type":"string"}},"required":["id","title","start","end"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/entries":{"get":{"summary":"List calendar entries in a bounded window","tags":["Calendar"],"description":"Retrieve calendar entries within a bounded time window with optional calendar filtering.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startsAt","required":true},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endsAt","required":true},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"calendarIds","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeCancelled","required":false},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["event","booking","reservation","hold","reminder_task"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"visibility":{"type":"string","enum":["default","private"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"localStartDate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"localEndDateExclusive":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"timezone":{"type":"string"},"isAllDay":{"type":"boolean"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"locationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationPayload":{"type":"object","additionalProperties":true},"scopeType":{"anyOf":[{"type":"string","enum":["resource","space","user"]},{"type":"null"}]},"scopeId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvalState":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},{"type":"null"}]},"approvalRequestId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","kind","status","visibility","title","startsAt","endsAt","localStartDate","localEndDateExclusive","timezone","isAllDay","ownerUserId","metadata","typeDefinitionId","locationName","locationPayload","scopeType","scopeId","approvalState","approvalRequestId","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create calendar entry","tags":["Calendar"],"description":"Create an event, booking, reservation, hold, or reminder task in a calendar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["event","booking","reservation","hold","reminder_task"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"visibility":{"type":"string","enum":["default","private"]},"title":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string","minLength":1,"maxLength":64},"isAllDay":{"type":"boolean"},"ownerUserId":{"type":"string","format":"uuid"},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"type":"string","format":"uuid"},"locationName":{"type":"string","maxLength":255},"locationPayload":{"type":"object","additionalProperties":true},"scopeType":{"type":"string","enum":["resource","space","user"]},"scopeId":{"type":"string","format":"uuid"}},"required":["calendarId","kind","title","startsAt","endsAt","timezone"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["event","booking","reservation","hold","reminder_task"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"visibility":{"type":"string","enum":["default","private"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"localStartDate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"localEndDateExclusive":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"timezone":{"type":"string"},"isAllDay":{"type":"boolean"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"locationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationPayload":{"type":"object","additionalProperties":true},"scopeType":{"anyOf":[{"type":"string","enum":["resource","space","user"]},{"type":"null"}]},"scopeId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvalState":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},{"type":"null"}]},"approvalRequestId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","kind","status","visibility","title","startsAt","endsAt","localStartDate","localEndDateExclusive","timezone","isAllDay","ownerUserId","metadata","typeDefinitionId","locationName","locationPayload","scopeType","scopeId","approvalState","approvalRequestId","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/recurrence-masters":{"post":{"summary":"Create recurrence master for a calendar entry","tags":["Calendar"],"description":"Create the recurrence rule and generation window for a recurring calendar entry.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"rootEntryId":{"type":"string","format":"uuid"},"frequency":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"intervalCount":{"type":"integer","minimum":1},"byWeekday":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},"byMonthDay":{"type":"array","items":{"type":"integer","minimum":1,"maximum":31}},"startsAt":{"type":"string","format":"date-time"},"untilAt":{"type":"string","format":"date-time"},"occurrenceCountLimit":{"type":"integer","minimum":1},"timezone":{"type":"string","minLength":1,"maxLength":64},"generatedWindowDays":{"type":"integer","minimum":1,"maximum":366},"metadata":{"type":"object","additionalProperties":true}},"required":["calendarId","rootEntryId","frequency","startsAt","timezone"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"rootEntryId":{"type":"string","format":"uuid"},"frequency":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"intervalCount":{"type":"integer","minimum":1},"byWeekday":{"anyOf":[{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},{"type":"null"}]},"byMonthDay":{"anyOf":[{"type":"array","items":{"type":"integer","minimum":1,"maximum":31}},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time"},"untilAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"occurrenceCountLimit":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}]},"timezone":{"type":"string"},"generatedWindowDays":{"type":"integer","minimum":1,"maximum":366},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","rootEntryId","frequency","intervalCount","byWeekday","byMonthDay","startsAt","untilAt","occurrenceCountLimit","timezone","generatedWindowDays","metadata","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/recurrence-masters/{id}":{"get":{"summary":"Get recurrence master by id","tags":["Calendar"],"description":"Retrieve the recurrence rule and metadata for a specific recurrence master.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"rootEntryId":{"type":"string","format":"uuid"},"frequency":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"intervalCount":{"type":"integer","minimum":1},"byWeekday":{"anyOf":[{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},{"type":"null"}]},"byMonthDay":{"anyOf":[{"type":"array","items":{"type":"integer","minimum":1,"maximum":31}},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time"},"untilAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"occurrenceCountLimit":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}]},"timezone":{"type":"string"},"generatedWindowDays":{"type":"integer","minimum":1,"maximum":366},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","rootEntryId","frequency","intervalCount","byWeekday","byMonthDay","startsAt","untilAt","occurrenceCountLimit","timezone","generatedWindowDays","metadata","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/recurrence-masters/{id}/instances":{"get":{"summary":"List recurrence instances in a bounded window","tags":["Calendar"],"description":"Retrieve generated and overridden recurrence instances for a recurrence master in a bounded window.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startsAt","required":true},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endsAt","required":true},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":200},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"recurrenceMasterId":{"type":"string","format":"uuid"},"sourceEntryId":{"type":"string","format":"uuid"},"instanceDate":{"type":"string","format":"date"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"localStartDate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"localEndDateExclusive":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"timezone":{"type":"string"},"isAllDay":{"type":"boolean"},"instanceState":{"type":"string","enum":["generated","overridden","cancelled"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"titleOverride":{"anyOf":[{"type":"string"},{"type":"null"}]},"descriptionOverride":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadataOverride":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","recurrenceMasterId","sourceEntryId","instanceDate","startsAt","endsAt","localStartDate","localEndDateExclusive","timezone","isAllDay","instanceState","status","titleOverride","descriptionOverride","metadataOverride","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/recurrence-instances/{id}":{"patch":{"summary":"Override or cancel a recurrence instance","tags":["Calendar"],"description":"Override timing, content, or status for a single generated recurrence instance.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string","minLength":1,"maxLength":64},"isAllDay":{"type":"boolean"},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"instanceState":{"type":"string","enum":["generated","overridden","cancelled"]},"titleOverride":{"type":"string","minLength":1,"maxLength":255},"descriptionOverride":{"type":"string"},"metadataOverride":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"recurrenceMasterId":{"type":"string","format":"uuid"},"sourceEntryId":{"type":"string","format":"uuid"},"instanceDate":{"type":"string","format":"date"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"localStartDate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"localEndDateExclusive":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"timezone":{"type":"string"},"isAllDay":{"type":"boolean"},"instanceState":{"type":"string","enum":["generated","overridden","cancelled"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"titleOverride":{"anyOf":[{"type":"string"},{"type":"null"}]},"descriptionOverride":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadataOverride":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","recurrenceMasterId","sourceEntryId","instanceDate","startsAt","endsAt","localStartDate","localEndDateExclusive","timezone","isAllDay","instanceState","status","titleOverride","descriptionOverride","metadataOverride","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/free-busy":{"get":{"summary":"Get free-busy aggregation for visible calendars","tags":["Calendar"],"description":"Retrieve aggregated busy intervals across visible calendars for the requested time window.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startsAt","required":true},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endsAt","required":true},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"calendarIds","required":false},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"resourceIds","required":false},{"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"in":"query","name":"spaceIds","required":false},{"schema":{"type":"string","enum":["occupied_ranges","free_slots"]},"in":"query","name":"mode","required":false},{"schema":{"type":"integer","minimum":1,"maximum":720},"in":"query","name":"slotDurationMinutes","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"windowStartsAt":{"type":"string","format":"date-time"},"windowEndsAt":{"type":"string","format":"date-time"},"mode":{"type":"string","enum":["occupied_ranges","free_slots"]},"slotDurationMinutes":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}]},"resolvedTargets":{"type":"object","properties":{"calendarIds":{"type":"array","items":{"type":"string","format":"uuid"}},"resourceIds":{"type":"array","items":{"type":"string","format":"uuid"}},"spaceIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["calendarIds","resourceIds","spaceIds"],"additionalProperties":false},"policy":{"type":"object","properties":{"maxWindowMinutes":{"type":"integer","minimum":1},"maxTargetIds":{"type":"integer","minimum":1},"blackoutRangeCount":{"type":"integer","minimum":0}},"required":["maxWindowMinutes","maxTargetIds","blackoutRangeCount"],"additionalProperties":false},"intervals":{"type":"array","items":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"classification":{"type":"string","enum":["occupied","blocked","free"]},"status":{"anyOf":[{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},{"type":"null"}]},"isAllDay":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["calendarId","startsAt","endsAt","classification","status","isAllDay"],"additionalProperties":false}}},"required":["windowStartsAt","windowEndsAt","mode","slotDurationMinutes","resolvedTargets","policy","intervals"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/{id}":{"get":{"summary":"Get calendar by id","tags":["Calendar"],"description":"Retrieve a calendar with its current configuration.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"type":"string"},"visibility":{"type":"string","enum":["private","shared","public_within_tenant"]},"policy":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"linkedEntity":{"type":"object","properties":{"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["userId","resourceId","spaceId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","kind","name","timezone","visibility","policy","metadata","typeDefinitionId","linkedEntity","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update calendar","tags":["Calendar"],"description":"Update calendar metadata, visibility, policy, or type definition settings.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"timezone":{"type":"string","minLength":1,"maxLength":64},"visibility":{"type":"string","enum":["private","shared","public_within_tenant"]},"policy":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"type":"string","format":"uuid"},"linkedResourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"linkedSpaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"linkedUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"type":"string"},"visibility":{"type":"string","enum":["private","shared","public_within_tenant"]},"policy":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"linkedEntity":{"type":"object","properties":{"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["userId","resourceId","spaceId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","kind","name","timezone","visibility","policy","metadata","typeDefinitionId","linkedEntity","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete calendar","tags":["Calendar"],"description":"Delete a calendar that the current user is allowed to manage.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/{id}/shares":{"get":{"summary":"List calendar shares","tags":["Calendar"],"description":"Retrieve the shares that grant access to a specific calendar.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"principalType":{"type":"string","enum":["user","group","tenant_role","system_role"]},"principalUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalGroupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalRole":{"anyOf":[{"type":"string"},{"type":"null"}]},"shareRole":{"type":"string","enum":["calendar_admin","calendar_manager","calendar_editor","calendar_contributor","calendar_viewer","calendar_free_busy"]},"grantsPrivateDetails":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","principalType","principalUserId","principalGroupId","principalRole","shareRole","grantsPrivateDetails","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"}},"required":["data","total"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create calendar share","tags":["Calendar"],"description":"Grant calendar access to a user, group, or role with a specific share role.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"principalType":{"type":"string","enum":["user","group","tenant_role","system_role"]},"principalUserId":{"type":"string","format":"uuid"},"principalGroupId":{"type":"string","format":"uuid"},"principalRole":{"type":"string","minLength":1,"maxLength":64},"shareRole":{"type":"string","enum":["calendar_admin","calendar_manager","calendar_editor","calendar_contributor","calendar_viewer","calendar_free_busy"]},"grantsPrivateDetails":{"type":"boolean"}},"required":["principalType","shareRole"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"principalType":{"type":"string","enum":["user","group","tenant_role","system_role"]},"principalUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalGroupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalRole":{"anyOf":[{"type":"string"},{"type":"null"}]},"shareRole":{"type":"string","enum":["calendar_admin","calendar_manager","calendar_editor","calendar_contributor","calendar_viewer","calendar_free_busy"]},"grantsPrivateDetails":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","principalType","principalUserId","principalGroupId","principalRole","shareRole","grantsPrivateDetails","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/{id}/reminders":{"get":{"summary":"List reminders for a calendar","tags":["Calendar"],"description":"Retrieve reminders configured for a calendar and its entries.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"calendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"recurrenceMasterId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"channel":{"type":"string","enum":["in_app","email","sms","webhook"]},"offsetMinutes":{"type":"integer","minimum":-10080,"maximum":10080},"isEnabled":{"type":"boolean"},"nextTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTriggeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","calendarEntryId","recurrenceMasterId","channel","offsetMinutes","isEnabled","nextTriggerAt","lastTriggeredAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"}},"required":["data","total"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/reminders":{"post":{"summary":"Create reminder for an entry or recurrence series","tags":["Calendar"],"description":"Create a reminder for a calendar entry or recurrence series with a chosen delivery channel.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"calendarEntryId":{"type":"string","format":"uuid"},"recurrenceMasterId":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["in_app","email","sms","webhook"]},"offsetMinutes":{"type":"integer","minimum":-10080,"maximum":10080},"isEnabled":{"type":"boolean"}},"required":["calendarId","channel","offsetMinutes"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"calendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"recurrenceMasterId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"channel":{"type":"string","enum":["in_app","email","sms","webhook"]},"offsetMinutes":{"type":"integer","minimum":-10080,"maximum":10080},"isEnabled":{"type":"boolean"},"nextTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTriggeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","calendarEntryId","recurrenceMasterId","channel","offsetMinutes","isEnabled","nextTriggerAt","lastTriggeredAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/{id}/reminders/dispatch-preview":{"post":{"summary":"Preview due reminders for dispatch without worker orchestration","tags":["Calendar"],"description":"Preview reminders that would be dispatched for a calendar without triggering worker execution.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"reminder":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"calendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"recurrenceMasterId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"channel":{"type":"string","enum":["in_app","email","sms","webhook"]},"offsetMinutes":{"type":"integer","minimum":-10080,"maximum":10080},"isEnabled":{"type":"boolean"},"nextTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTriggeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","calendarEntryId","recurrenceMasterId","channel","offsetMinutes","isEnabled","nextTriggerAt","lastTriggeredAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false},"targetKind":{"type":"string","enum":["entry","recurrence_instance"]},"targetId":{"type":"string","format":"uuid"},"targetStartsAt":{"type":"string","format":"date-time"},"targetEndsAt":{"type":"string","format":"date-time"},"targetTimezone":{"type":"string"},"deliveryKey":{"type":"string"}},"required":["reminder","targetKind","targetId","targetStartsAt","targetEndsAt","targetTimezone","deliveryKey"],"additionalProperties":false}},"total":{"type":"integer"}},"required":["data","total"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/{id}/reminders/dispatch":{"post":{"summary":"Dispatch due reminders through the canonical notification platform","tags":["Calendar"],"description":"Publish due reminders for a calendar through the unified notification inbox and advance each dispatched reminder to its next trigger time.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"reminder":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"calendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"recurrenceMasterId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"channel":{"type":"string","enum":["in_app","email","sms","webhook"]},"offsetMinutes":{"type":"integer","minimum":-10080,"maximum":10080},"isEnabled":{"type":"boolean"},"nextTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTriggeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","calendarEntryId","recurrenceMasterId","channel","offsetMinutes","isEnabled","nextTriggerAt","lastTriggeredAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false},"targetKind":{"type":"string","enum":["entry","recurrence_instance"]},"targetId":{"type":"string","format":"uuid"},"targetStartsAt":{"type":"string","format":"date-time"},"targetEndsAt":{"type":"string","format":"date-time"},"targetTimezone":{"type":"string"},"deliveryKey":{"type":"string"}},"required":["reminder","targetKind","targetId","targetStartsAt","targetEndsAt","targetTimezone","deliveryKey"],"additionalProperties":false}},"total":{"type":"integer"}},"required":["data","total"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/reminders/{id}/ack":{"post":{"summary":"Acknowledge reminder dispatch and advance the next trigger","tags":["Calendar"],"description":"Acknowledge a reminder dispatch event and advance the reminder to its next trigger time.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"triggeredAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"calendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"recurrenceMasterId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"channel":{"type":"string","enum":["in_app","email","sms","webhook"]},"offsetMinutes":{"type":"integer","minimum":-10080,"maximum":10080},"isEnabled":{"type":"boolean"},"nextTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTriggeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","calendarEntryId","recurrenceMasterId","channel","offsetMinutes","isEnabled","nextTriggerAt","lastTriggeredAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/reminders/{id}":{"delete":{"summary":"Delete calendar reminder","tags":["Calendar"],"description":"Delete a reminder from the calendar reminder schedule.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/entries/{id}":{"get":{"summary":"Get calendar entry by id","tags":["Calendar"],"description":"Retrieve a specific calendar entry with its current state and metadata.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["event","booking","reservation","hold","reminder_task"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"visibility":{"type":"string","enum":["default","private"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"localStartDate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"localEndDateExclusive":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"timezone":{"type":"string"},"isAllDay":{"type":"boolean"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"locationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationPayload":{"type":"object","additionalProperties":true},"scopeType":{"anyOf":[{"type":"string","enum":["resource","space","user"]},{"type":"null"}]},"scopeId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvalState":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},{"type":"null"}]},"approvalRequestId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","kind","status","visibility","title","startsAt","endsAt","localStartDate","localEndDateExclusive","timezone","isAllDay","ownerUserId","metadata","typeDefinitionId","locationName","locationPayload","scopeType","scopeId","approvalState","approvalRequestId","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update calendar entry","tags":["Calendar"],"description":"Update the content, timing, visibility, or metadata of a calendar entry.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"kind":{"type":"string","enum":["event","booking","reservation","hold","reminder_task"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"visibility":{"type":"string","enum":["default","private"]},"title":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string","minLength":1,"maxLength":64},"isAllDay":{"type":"boolean"},"ownerUserId":{"type":"string","format":"uuid"},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"type":"string","format":"uuid"},"locationName":{"type":"string","maxLength":255},"locationPayload":{"type":"object","additionalProperties":true},"scopeType":{"anyOf":[{"type":"string","enum":["resource","space","user"]},{"type":"null"}]},"scopeId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["event","booking","reservation","hold","reminder_task"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"visibility":{"type":"string","enum":["default","private"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"localStartDate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"localEndDateExclusive":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"timezone":{"type":"string"},"isAllDay":{"type":"boolean"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"locationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationPayload":{"type":"object","additionalProperties":true},"scopeType":{"anyOf":[{"type":"string","enum":["resource","space","user"]},{"type":"null"}]},"scopeId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvalState":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},{"type":"null"}]},"approvalRequestId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","kind","status","visibility","title","startsAt","endsAt","localStartDate","localEndDateExclusive","timezone","isAllDay","ownerUserId","metadata","typeDefinitionId","locationName","locationPayload","scopeType","scopeId","approvalState","approvalRequestId","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete calendar entry","tags":["Calendar"],"description":"Delete a calendar entry from the calendar timeline.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/entries/{id}/status":{"post":{"summary":"Transition booking status","tags":["Calendar"],"description":"Change the workflow status of a booking or calendar entry.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]}},"required":["status"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["event","booking","reservation","hold","reminder_task"]},"status":{"type":"string","enum":["draft","tentative","confirmed","cancelled","completed"]},"visibility":{"type":"string","enum":["default","private"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"localStartDate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"localEndDateExclusive":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"timezone":{"type":"string"},"isAllDay":{"type":"boolean"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"locationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationPayload":{"type":"object","additionalProperties":true},"scopeType":{"anyOf":[{"type":"string","enum":["resource","space","user"]},{"type":"null"}]},"scopeId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvalState":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","cancelled","expired"]},{"type":"null"}]},"approvalRequestId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","kind","status","visibility","title","startsAt","endsAt","localStartDate","localEndDateExclusive","timezone","isAllDay","ownerUserId","metadata","typeDefinitionId","locationName","locationPayload","scopeType","scopeId","approvalState","approvalRequestId","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/entries/{id}/respond":{"post":{"summary":"Respond to calendar assignment","tags":["Calendar"],"description":"Record the current user's response to a calendar assignment or participation request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"responseStatus":{"type":"string","enum":["pending","accepted","declined","tentative"]}},"required":["responseStatus"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarEntryId":{"type":"string","format":"uuid"},"actorType":{"type":"string","enum":["user","group"]},"actorUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorGroupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"role":{"type":"string","enum":["attendee","assignee","owner","observer"]},"responseStatus":{"type":"string","enum":["pending","accepted","declined","tentative"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarEntryId","actorType","actorUserId","actorGroupId","role","responseStatus","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar-groups/":{"get":{"summary":"List calendar groups","tags":["Calendar Groups"],"description":"List calendar groups for the tenant. Groups define a broadcast source calendar whose entries are virtually merged into all member calendars.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceCalendarId":{"type":"string","format":"uuid"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","name","sourceCalendarId","ownerUserId","metadata","memberCount","createdAt","updatedAt","createdBy"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create calendar group","tags":["Calendar Groups"],"description":"Create a calendar group. The sourceCalendarId is the broadcast calendar whose entries will be merged into all member calendars at query time.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"sourceCalendarId":{"type":"string","format":"uuid"},"metadata":{"type":"object","additionalProperties":true}},"required":["name","sourceCalendarId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceCalendarId":{"type":"string","format":"uuid"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","name","sourceCalendarId","ownerUserId","metadata","memberCount","createdAt","updatedAt","createdBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar-groups/{id}":{"get":{"summary":"Get calendar group","tags":["Calendar Groups"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceCalendarId":{"type":"string","format":"uuid"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","name","sourceCalendarId","ownerUserId","metadata","memberCount","createdAt","updatedAt","createdBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update calendar group","tags":["Calendar Groups"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceCalendarId":{"type":"string","format":"uuid"},"ownerUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","name","sourceCalendarId","ownerUserId","metadata","memberCount","createdAt","updatedAt","createdBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete calendar group","tags":["Calendar Groups"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar-groups/{id}/members":{"get":{"summary":"List calendar group members","tags":["Calendar Groups"],"description":"List all member calendars in a group.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"groupId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"calendarName":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","groupId","calendarId","calendarName","label","sortOrder","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Add calendar to group","tags":["Calendar Groups"],"description":"Add a calendar as a member of this group. Its window and free/busy results will automatically include all entries from the group source calendar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"label":{"type":"string","maxLength":255},"sortOrder":{"type":"integer","minimum":0}},"required":["calendarId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"groupId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"calendarName":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","groupId","calendarId","calendarName","label","sortOrder","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar-groups/{id}/members/{memberId}":{"delete":{"summary":"Remove calendar from group","tags":["Calendar Groups"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"memberId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/":{"get":{"summary":"List tenant admin calendars","tags":["Calendar Admin"],"description":"Retrieve calendars in the tenant from an administrative perspective with filtering and pagination.","parameters":[{"schema":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"in":"query","name":"kind","required":false},{"schema":{"type":"string","enum":["tenant","user","resource","space"]},"in":"query","name":"linkType","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"linkedUserId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"linkedResourceId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"linkedSpaceId","required":false},{"schema":{"type":"string","enum":["private","shared","public_within_tenant"]},"in":"query","name":"visibility","required":false},{"schema":{"type":"string","enum":["active","deleted","all"]},"in":"query","name":"activeState","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"visibility":{"type":"string","enum":["private","shared","public_within_tenant"]},"timezone":{"type":"string"},"activeState":{"type":"string","enum":["active","deleted"]},"linkedParent":{"type":"object","properties":{"linkType":{"type":"string","enum":["tenant","user","resource","space"]},"entityId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"entityName":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessMode":{"type":"string","enum":["tenant_shared","linked_parent"]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["linkType","entityId","entityName","accessMode","note"],"additionalProperties":false},"policySummary":{"type":"object","properties":{"sharePosture":{"type":"string","enum":["private","shared","public_within_tenant"]},"visibilityDefault":{"type":"string","enum":["private","shared","public_within_tenant"]},"bookingPolicy":{"type":"object","additionalProperties":true},"reminderDefaults":{"type":"object","additionalProperties":true},"adminNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"editableFields":{"type":"array","items":{"type":"string","enum":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes"]}},"provenance":{"type":"object","properties":{"sharePosture":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"visibilityDefault":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"bookingPolicy":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"reminderDefaults":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"adminNotes":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]}},"required":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes"],"additionalProperties":false}},"required":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes","editableFields","provenance"],"additionalProperties":false},"stats":{"type":"object","properties":{"explicitShareCount":{"type":"integer"},"enabledReminderCount":{"type":"integer"},"nextReminderTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["explicitShareCount","enabledReminderCount","nextReminderTriggerAt"],"additionalProperties":false},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","kind","visibility","timezone","activeState","linkedParent","policySummary","stats","updatedAt"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}":{"get":{"summary":"Get tenant admin calendar detail","tags":["Calendar Admin"],"description":"Retrieve administrative calendar detail including policy, shares, and operational context.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calendar":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["user_linked","resource_linked","space_linked","tenant_shared"]},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"type":"string"},"visibility":{"type":"string","enum":["private","shared","public_within_tenant"]},"policy":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"typeDefinitionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"linkedEntity":{"type":"object","properties":{"userId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["userId","resourceId","spaceId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","kind","name","timezone","visibility","policy","metadata","typeDefinitionId","linkedEntity","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false},"linkedParent":{"type":"object","properties":{"linkType":{"type":"string","enum":["tenant","user","resource","space"]},"entityId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"entityName":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessMode":{"type":"string","enum":["tenant_shared","linked_parent"]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["linkType","entityId","entityName","accessMode","note"],"additionalProperties":false},"policy":{"type":"object","properties":{"sharePosture":{"type":"string","enum":["private","shared","public_within_tenant"]},"visibilityDefault":{"type":"string","enum":["private","shared","public_within_tenant"]},"bookingPolicy":{"type":"object","additionalProperties":true},"reminderDefaults":{"type":"object","additionalProperties":true},"adminNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"editableFields":{"type":"array","items":{"type":"string","enum":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes"]}},"provenance":{"type":"object","properties":{"sharePosture":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"visibilityDefault":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"bookingPolicy":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"reminderDefaults":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"adminNotes":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]}},"required":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes"],"additionalProperties":false}},"required":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes","editableFields","provenance"],"additionalProperties":false},"statistics":{"type":"object","properties":{"explicitShareCount":{"type":"integer"},"totalReminderCount":{"type":"integer"},"enabledReminderCount":{"type":"integer"},"nextReminderTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"futureEntryCount":{"type":"integer"},"futureInstanceCount":{"type":"integer"}},"required":["explicitShareCount","totalReminderCount","enabledReminderCount","nextReminderTriggerAt","futureEntryCount","futureInstanceCount"],"additionalProperties":false}},"required":["calendar","linkedParent","policy","statistics"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/policy":{"patch":{"summary":"Update tenant admin calendar policy","tags":["Calendar Admin"],"description":"Update policy defaults, booking policy, reminder defaults, and admin notes for a calendar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"sharePosture":{"type":"string","enum":["private","shared","public_within_tenant"]},"visibilityDefault":{"type":"string","enum":["private","shared","public_within_tenant"]},"bookingPolicy":{"type":"object","additionalProperties":true},"reminderDefaults":{"type":"object","additionalProperties":true},"adminNotes":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sharePosture":{"type":"string","enum":["private","shared","public_within_tenant"]},"visibilityDefault":{"type":"string","enum":["private","shared","public_within_tenant"]},"bookingPolicy":{"type":"object","additionalProperties":true},"reminderDefaults":{"type":"object","additionalProperties":true},"adminNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"editableFields":{"type":"array","items":{"type":"string","enum":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes"]}},"provenance":{"type":"object","properties":{"sharePosture":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"visibilityDefault":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"bookingPolicy":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"reminderDefaults":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]},"adminNotes":{"type":"string","enum":["calendar_override","calendar_default","linked_parent_inherited"]}},"required":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes"],"additionalProperties":false}},"required":["sharePosture","visibilityDefault","bookingPolicy","reminderDefaults","adminNotes","editableFields","provenance"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/shares":{"get":{"summary":"Get tenant admin calendar shares summary","tags":["Calendar Admin"],"description":"Retrieve the current share configuration summary for a calendar from the tenant admin surface.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"explicitShares":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"principalType":{"type":"string","enum":["user","group","tenant_role","system_role"]},"principalUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalGroupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalRole":{"anyOf":[{"type":"string"},{"type":"null"}]},"shareRole":{"type":"string","enum":["calendar_admin","calendar_manager","calendar_editor","calendar_contributor","calendar_viewer","calendar_free_busy"]},"grantsPrivateDetails":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","principalType","principalUserId","principalGroupId","principalRole","shareRole","grantsPrivateDetails","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"inheritedAccess":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["tenant_admin","linked_parent","calendar_visibility"]},"effectiveRole":{"type":"string"},"title":{"type":"string"},"details":{"anyOf":[{"type":"string"},{"type":"null"}]},"editable":{"type":"boolean"}},"required":["source","effectiveRole","title","details","editable"],"additionalProperties":false}},"totalExplicitShares":{"type":"integer"}},"required":["calendarId","explicitShares","inheritedAccess","totalExplicitShares"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create explicit tenant admin calendar share","tags":["Calendar Admin"],"description":"Create an explicit share for a calendar with tenant-admin permissions and share-role controls.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"principalType":{"type":"string","enum":["user","group","tenant_role","system_role"]},"principalUserId":{"type":"string","format":"uuid"},"principalGroupId":{"type":"string","format":"uuid"},"principalRole":{"type":"string","minLength":1,"maxLength":64},"shareRole":{"type":"string","enum":["calendar_admin","calendar_manager","calendar_editor","calendar_contributor","calendar_viewer","calendar_free_busy"]},"grantsPrivateDetails":{"type":"boolean"}},"required":["principalType","shareRole"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"principalType":{"type":"string","enum":["user","group","tenant_role","system_role"]},"principalUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalGroupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalRole":{"anyOf":[{"type":"string"},{"type":"null"}]},"shareRole":{"type":"string","enum":["calendar_admin","calendar_manager","calendar_editor","calendar_contributor","calendar_viewer","calendar_free_busy"]},"grantsPrivateDetails":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","principalType","principalUserId","principalGroupId","principalRole","shareRole","grantsPrivateDetails","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/shares/{shareId}":{"patch":{"summary":"Update explicit tenant admin calendar share","tags":["Calendar Admin"],"description":"Update the role or private-details access of an existing calendar share.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"shareRole":{"type":"string","enum":["calendar_admin","calendar_manager","calendar_editor","calendar_contributor","calendar_viewer","calendar_free_busy"]},"grantsPrivateDetails":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"shareId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"principalType":{"type":"string","enum":["user","group","tenant_role","system_role"]},"principalUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalGroupId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"principalRole":{"anyOf":[{"type":"string"},{"type":"null"}]},"shareRole":{"type":"string","enum":["calendar_admin","calendar_manager","calendar_editor","calendar_contributor","calendar_viewer","calendar_free_busy"]},"grantsPrivateDetails":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","principalType","principalUserId","principalGroupId","principalRole","shareRole","grantsPrivateDetails","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete explicit tenant admin calendar share","tags":["Calendar Admin"],"description":"Delete an explicit share from a calendar in the tenant admin surface.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"shareId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/reminders":{"get":{"summary":"Get tenant admin reminder health summary","tags":["Calendar Admin"],"description":"Retrieve reminder health, counts, and configuration state for a calendar from the tenant admin surface.","parameters":[{"schema":{"type":"boolean","default":true},"in":"query","name":"includeDisabled","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"summary":{"type":"object","properties":{"total":{"type":"integer"},"enabled":{"type":"integer"},"disabled":{"type":"integer"},"dueCount":{"type":"integer"},"nextTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"channels":{"type":"object","properties":{"in_app":{"type":"integer"},"email":{"type":"integer"},"sms":{"type":"integer"},"webhook":{"type":"integer"}},"required":["in_app","email","sms","webhook"],"additionalProperties":false}},"required":["total","enabled","disabled","dueCount","nextTriggerAt","channels"],"additionalProperties":false},"reminders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"calendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"recurrenceMasterId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"channel":{"type":"string","enum":["in_app","email","sms","webhook"]},"offsetMinutes":{"type":"integer","minimum":-10080,"maximum":10080},"isEnabled":{"type":"boolean"},"nextTriggerAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastTriggeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","calendarEntryId","recurrenceMasterId","channel","offsetMinutes","isEnabled","nextTriggerAt","lastTriggeredAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["calendarId","summary","reminders","total","limit","offset"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/operations":{"get":{"summary":"Get bounded tenant admin calendar operations summary","tags":["Calendar Admin"],"description":"Retrieve a bounded operational summary for a calendar, including upcoming and recent activity.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"asOf","required":false},{"schema":{"type":"integer","minimum":1,"maximum":180,"default":30},"in":"query","name":"futureWindowDays","required":false},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"in":"query","name":"recentLimit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"asOf":{"type":"string","format":"date-time"},"futureWindowDays":{"type":"integer"},"counters":{"type":"object","properties":{"futureEntryCount":{"type":"integer"},"futureInstanceCount":{"type":"integer"},"pendingReminderCount":{"type":"integer"},"recentMutationCount":{"type":"integer"}},"required":["futureEntryCount","futureInstanceCount","pendingReminderCount","recentMutationCount"],"additionalProperties":false},"recentMutations":{"type":"array","items":{"type":"object","properties":{"entityType":{"type":"string","enum":["calendar","share","reminder","entry"]},"entityId":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["created","updated","deleted"]},"occurredAt":{"type":"string","format":"date-time"},"summary":{"type":"string"}},"required":["entityType","entityId","action","occurredAt","summary"],"additionalProperties":false}},"dispatchFailures":{"type":"object","properties":{"available":{"type":"boolean"},"count":{"type":"integer"},"note":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["available","count","note"],"additionalProperties":false}},"required":["calendarId","asOf","futureWindowDays","counters","recentMutations","dispatchFailures"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/booking-requests":{"get":{"summary":"List booking requests","tags":["Calendar Booking"],"description":"List booking requests for the current user or, when permitted, for a managed calendar.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"calendarId","required":false},{"schema":{"type":"string","enum":["pending","approved","denied","cancelled","waitlisted"]},"in":"query","name":"state","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"mine","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"requestedByUserId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["pending","approved","denied","cancelled","waitlisted"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedStartsAt":{"type":"string","format":"date-time"},"requestedEndsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"requestedSlotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"waitlistPosition":{"anyOf":[{"type":"integer"},{"type":"null"}]},"decisionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"bookingReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chatReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"resultingCalendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cancelledByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","requestedByUserId","state","title","description","requestedStartsAt","requestedEndsAt","timezone","requestedSlotDurationMinutes","waitlistPosition","decisionReason","ownerNotes","bookingReferenceId","chatReferenceId","resultingCalendarEntryId","approvedByUserId","approvedAt","deniedByUserId","deniedAt","cancelledByUserId","cancelledAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create booking request","tags":["Calendar Booking"],"description":"Create a booking request for a calendar window and optionally join the waitlist when allowed.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"calendarId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":4000},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string","minLength":1,"maxLength":64},"requestedSlotDurationMinutes":{"type":"integer","minimum":1,"maximum":720},"allowWaitlist":{"type":"boolean"},"bookingReferenceId":{"type":"string","maxLength":128},"chatReferenceId":{"type":"string","maxLength":128}},"required":["calendarId","title","startsAt","endsAt","timezone"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"requestedByUserId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["pending","approved","denied","cancelled","waitlisted"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedStartsAt":{"type":"string","format":"date-time"},"requestedEndsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"requestedSlotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"waitlistPosition":{"anyOf":[{"type":"integer"},{"type":"null"}]},"decisionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"bookingReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chatReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"resultingCalendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cancelledByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","requestedByUserId","state","title","description","requestedStartsAt","requestedEndsAt","timezone","requestedSlotDurationMinutes","waitlistPosition","decisionReason","ownerNotes","bookingReferenceId","chatReferenceId","resultingCalendarEntryId","approvedByUserId","approvedAt","deniedByUserId","deniedAt","cancelledByUserId","cancelledAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/booking-requests/{id}/approve":{"post":{"summary":"Approve booking request","tags":["Calendar Booking"],"description":"Approve a pending or waitlisted booking request and create the resulting calendar booking entry.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ownerNotes":{"type":"string","maxLength":4000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"requestedByUserId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["pending","approved","denied","cancelled","waitlisted"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedStartsAt":{"type":"string","format":"date-time"},"requestedEndsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"requestedSlotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"waitlistPosition":{"anyOf":[{"type":"integer"},{"type":"null"}]},"decisionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"bookingReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chatReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"resultingCalendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cancelledByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","requestedByUserId","state","title","description","requestedStartsAt","requestedEndsAt","timezone","requestedSlotDurationMinutes","waitlistPosition","decisionReason","ownerNotes","bookingReferenceId","chatReferenceId","resultingCalendarEntryId","approvedByUserId","approvedAt","deniedByUserId","deniedAt","cancelledByUserId","cancelledAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/booking-requests/{id}/deny":{"post":{"summary":"Deny booking request","tags":["Calendar Booking"],"description":"Deny a booking request with a required reason and optional owner notes.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":4000},"ownerNotes":{"type":"string","maxLength":4000}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"requestedByUserId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["pending","approved","denied","cancelled","waitlisted"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedStartsAt":{"type":"string","format":"date-time"},"requestedEndsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"requestedSlotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"waitlistPosition":{"anyOf":[{"type":"integer"},{"type":"null"}]},"decisionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"bookingReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chatReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"resultingCalendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cancelledByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","requestedByUserId","state","title","description","requestedStartsAt","requestedEndsAt","timezone","requestedSlotDurationMinutes","waitlistPosition","decisionReason","ownerNotes","bookingReferenceId","chatReferenceId","resultingCalendarEntryId","approvedByUserId","approvedAt","deniedByUserId","deniedAt","cancelledByUserId","cancelledAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/calendar/booking-requests/{id}/cancel":{"post":{"summary":"Cancel booking request","tags":["Calendar Booking"],"description":"Cancel a booking request and cancel the resulting booking entry when the request was already approved.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"requestedByUserId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["pending","approved","denied","cancelled","waitlisted"]},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedStartsAt":{"type":"string","format":"date-time"},"requestedEndsAt":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"requestedSlotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"waitlistPosition":{"anyOf":[{"type":"integer"},{"type":"null"}]},"decisionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"bookingReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chatReferenceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"resultingCalendarEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cancelledByUserId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"cancelledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","requestedByUserId","state","title","description","requestedStartsAt","requestedEndsAt","timezone","requestedSlotDurationMinutes","waitlistPosition","decisionReason","ownerNotes","bookingReferenceId","chatReferenceId","resultingCalendarEntryId","approvedByUserId","approvedAt","deniedByUserId","deniedAt","cancelledByUserId","cancelledAt","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/scheduling-policy":{"get":{"summary":"Get calendar scheduling policy","tags":["Calendar Admin"],"description":"Retrieve the persisted scheduling policy for a calendar.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"strategy":{"type":"string","enum":["open_by_default","closed_by_default"]},"defaultSlotDurationMinutes":{"type":"integer","minimum":1,"maximum":720},"minNoticeMinutes":{"type":"integer","minimum":0},"bookingHorizonDays":{"type":"integer","minimum":1,"maximum":366},"maxWindowMinutes":{"type":"integer","minimum":1},"maxTargetIds":{"type":"integer","minimum":1,"maximum":100},"allowWaitlist":{"type":"boolean"},"requiresApproval":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","strategy","defaultSlotDurationMinutes","minNoticeMinutes","bookingHorizonDays","maxWindowMinutes","maxTargetIds","allowWaitlist","requiresApproval","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update calendar scheduling policy","tags":["Calendar Admin"],"description":"Update the persisted scheduling policy that drives free-busy and booking behavior for a calendar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"strategy":{"type":"string","enum":["open_by_default","closed_by_default"]},"defaultSlotDurationMinutes":{"type":"integer","minimum":1,"maximum":720},"minNoticeMinutes":{"type":"integer","minimum":0,"maximum":525600},"bookingHorizonDays":{"type":"integer","minimum":1,"maximum":366},"maxWindowMinutes":{"type":"integer","minimum":1,"maximum":525600},"maxTargetIds":{"type":"integer","minimum":1,"maximum":100},"allowWaitlist":{"type":"boolean"},"requiresApproval":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"strategy":{"type":"string","enum":["open_by_default","closed_by_default"]},"defaultSlotDurationMinutes":{"type":"integer","minimum":1,"maximum":720},"minNoticeMinutes":{"type":"integer","minimum":0},"bookingHorizonDays":{"type":"integer","minimum":1,"maximum":366},"maxWindowMinutes":{"type":"integer","minimum":1},"maxTargetIds":{"type":"integer","minimum":1,"maximum":100},"allowWaitlist":{"type":"boolean"},"requiresApproval":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","strategy","defaultSlotDurationMinutes","minNoticeMinutes","bookingHorizonDays","maxWindowMinutes","maxTargetIds","allowWaitlist","requiresApproval","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/availability-rules":{"get":{"summary":"List calendar availability rules","tags":["Calendar Admin"],"description":"List recurring weekly availability rules for a calendar.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"availabilityKind":{"type":"string","enum":["available","unavailable"]},"weekday":{"type":"integer","minimum":0,"maximum":6},"startMinuteOfDay":{"type":"integer","minimum":0,"maximum":1439},"endMinuteOfDay":{"type":"integer","minimum":1,"maximum":1440},"validFrom":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"validUntil":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"slotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","availabilityKind","weekday","startMinuteOfDay","endMinuteOfDay","validFrom","validUntil","slotDurationMinutes","note","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"}},"required":["data","total"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create calendar availability rule","tags":["Calendar Admin"],"description":"Create a recurring weekly availability or blackout rule for a calendar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"availabilityKind":{"type":"string","enum":["available","unavailable"]},"weekday":{"type":"integer","minimum":0,"maximum":6},"startMinuteOfDay":{"type":"integer","minimum":0,"maximum":1439},"endMinuteOfDay":{"type":"integer","minimum":1,"maximum":1440},"validFrom":{"type":"string","format":"date"},"validUntil":{"type":"string","format":"date"},"slotDurationMinutes":{"type":"integer","minimum":1,"maximum":720},"note":{"type":"string","maxLength":1000}},"required":["availabilityKind","weekday","startMinuteOfDay","endMinuteOfDay"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"availabilityKind":{"type":"string","enum":["available","unavailable"]},"weekday":{"type":"integer","minimum":0,"maximum":6},"startMinuteOfDay":{"type":"integer","minimum":0,"maximum":1439},"endMinuteOfDay":{"type":"integer","minimum":1,"maximum":1440},"validFrom":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"validUntil":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"slotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","availabilityKind","weekday","startMinuteOfDay","endMinuteOfDay","validFrom","validUntil","slotDurationMinutes","note","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/availability-rules/{ruleId}":{"patch":{"summary":"Update calendar availability rule","tags":["Calendar Admin"],"description":"Update a recurring weekly availability or blackout rule for a calendar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"availabilityKind":{"type":"string","enum":["available","unavailable"]},"weekday":{"type":"integer","minimum":0,"maximum":6},"startMinuteOfDay":{"type":"integer","minimum":0,"maximum":1439},"endMinuteOfDay":{"type":"integer","minimum":1,"maximum":1440},"validFrom":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"validUntil":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"slotDurationMinutes":{"anyOf":[{"type":"integer","minimum":1,"maximum":720},{"type":"null"}]},"note":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"ruleId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"availabilityKind":{"type":"string","enum":["available","unavailable"]},"weekday":{"type":"integer","minimum":0,"maximum":6},"startMinuteOfDay":{"type":"integer","minimum":0,"maximum":1439},"endMinuteOfDay":{"type":"integer","minimum":1,"maximum":1440},"validFrom":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"validUntil":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"slotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","availabilityKind","weekday","startMinuteOfDay","endMinuteOfDay","validFrom","validUntil","slotDurationMinutes","note","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete calendar availability rule","tags":["Calendar Admin"],"description":"Soft-delete a recurring weekly availability rule for a calendar.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"ruleId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/availability-exceptions":{"get":{"summary":"List calendar availability exceptions","tags":["Calendar Admin"],"description":"List one-off availability or blackout exceptions for a calendar.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"availabilityKind":{"type":"string","enum":["available","unavailable"]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"slotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","availabilityKind","startsAt","endsAt","slotDurationMinutes","note","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"total":{"type":"integer"}},"required":["data","total"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create calendar availability exception","tags":["Calendar Admin"],"description":"Create a one-off availability or blackout exception for a calendar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"availabilityKind":{"type":"string","enum":["available","unavailable"]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"slotDurationMinutes":{"type":"integer","minimum":1,"maximum":720},"note":{"type":"string","maxLength":1000}},"required":["availabilityKind","startsAt","endsAt"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"availabilityKind":{"type":"string","enum":["available","unavailable"]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"slotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","availabilityKind","startsAt","endsAt","slotDurationMinutes","note","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/calendars/{calendarId}/availability-exceptions/{exceptionId}":{"patch":{"summary":"Update calendar availability exception","tags":["Calendar Admin"],"description":"Update a one-off availability or blackout exception for a calendar.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"availabilityKind":{"type":"string","enum":["available","unavailable"]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"slotDurationMinutes":{"anyOf":[{"type":"integer","minimum":1,"maximum":720},{"type":"null"}]},"note":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"exceptionId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"calendarId":{"type":"string","format":"uuid"},"availabilityKind":{"type":"string","enum":["available","unavailable"]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"slotDurationMinutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deletedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","calendarId","availabilityKind","startsAt","endsAt","slotDurationMinutes","note","createdAt","updatedAt","createdBy","deletedAt","deletedBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete calendar availability exception","tags":["Calendar Admin"],"description":"Soft-delete a one-off availability exception for a calendar.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"calendarId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"exceptionId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/network":{"get":{"summary":"Resolve network-based geo country information","tags":["Geo-Location"],"description":"Resolve the current request country from trusted edge headers and normalized network metadata.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"state":{"type":"string","enum":["ok","error"]},"message":{"type":"string"},"source":{"type":"string","enum":["cloudflare-header","trusted-forwarded-ip","socket-ip","unknown"]},"precision":{"type":"string","enum":["country","approximate","unknown"]},"clientIp":{"type":"string","nullable":true},"country":{"type":"object","properties":{"alpha2":{"type":"string","pattern":"^[A-Z]{2}$"},"alpha3":{"type":"string","pattern":"^[A-Z]{3}$","nullable":true},"name":{"type":"string"},"region":{"type":"string","nullable":true}},"required":["alpha2","alpha3","name","region"],"additionalProperties":false,"nullable":true},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[a-z]{2}$"},"name":{"type":"string"},"localName":{"type":"string"}},"required":["code","name","localName"],"additionalProperties":false}},"coordinates":{"type":"object","properties":{"decimal":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"],"additionalProperties":false},"latLng":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"lngLat":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"geoJsonPoint":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}},"required":["type","coordinates"],"additionalProperties":false}},"required":["decimal","latLng","lngLat","geoJsonPoint"],"additionalProperties":false,"nullable":true},"network":{"type":"object","properties":{"trustedHeaders":{"type":"array","items":{"type":"string"}},"countryHeader":{"type":"string","nullable":true},"provider":{"type":"string","enum":["cloudflare","ipinfo"],"nullable":true},"socketIp":{"type":"string","nullable":true},"forwardedIp":{"type":"string","nullable":true},"normalizedCountryCode":{"type":"string","pattern":"^[A-Z]{2,3}$","nullable":true}},"required":["trustedHeaders","countryHeader","provider","socketIp","forwardedIp","normalizedCountryCode"],"additionalProperties":false}},"required":["state","source","precision","clientIp","country","languages","coordinates","network"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/network-config":{"get":{"summary":"Resolve effective geo network config","tags":["Geo-Location"],"description":"Resolve the effective geo network config for the current request using country, tenant default, and system default fallback.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"state":{"type":"string","enum":["ok","error"]},"message":{"type":"string"},"detection":{"type":"object","properties":{"state":{"type":"string","enum":["ok","error"]},"message":{"type":"string"},"source":{"type":"string","enum":["cloudflare-header","trusted-forwarded-ip","socket-ip","unknown"]},"precision":{"type":"string","enum":["country","approximate","unknown"]},"clientIp":{"type":"string","nullable":true},"country":{"type":"object","properties":{"alpha2":{"type":"string","pattern":"^[A-Z]{2}$"},"alpha3":{"type":"string","pattern":"^[A-Z]{3}$","nullable":true},"name":{"type":"string"},"region":{"type":"string","nullable":true}},"required":["alpha2","alpha3","name","region"],"additionalProperties":false,"nullable":true},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[a-z]{2}$"},"name":{"type":"string"},"localName":{"type":"string"}},"required":["code","name","localName"],"additionalProperties":false}},"coordinates":{"type":"object","properties":{"decimal":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"],"additionalProperties":false},"latLng":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"lngLat":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"geoJsonPoint":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}},"required":["type","coordinates"],"additionalProperties":false}},"required":["decimal","latLng","lngLat","geoJsonPoint"],"additionalProperties":false,"nullable":true},"network":{"type":"object","properties":{"trustedHeaders":{"type":"array","items":{"type":"string"}},"countryHeader":{"type":"string","nullable":true},"provider":{"type":"string","enum":["cloudflare","ipinfo"],"nullable":true},"socketIp":{"type":"string","nullable":true},"forwardedIp":{"type":"string","nullable":true},"normalizedCountryCode":{"type":"string","pattern":"^[A-Z]{2,3}$","nullable":true}},"required":["trustedHeaders","countryHeader","provider","socketIp","forwardedIp","normalizedCountryCode"],"additionalProperties":false}},"required":["state","source","precision","clientIp","country","languages","coordinates","network"],"additionalProperties":false},"appliedConfig":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"typeDefinitionId":{"type":"string","format":"uuid"},"countryCodes":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2,3}$"}},"properties":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"matchType":{"type":"string","enum":["country","tenant-default","system-default"]}},"required":["id","tenantId","name","description","isDefault","typeDefinitionId","countryCodes","properties","createdAt","updatedAt","createdBy","matchType"],"additionalProperties":false,"nullable":true},"typeDefinition":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"typeName":{"type":"string"},"label":{"type":"string"},"tenantId":{"type":"string","format":"uuid"},"isSystem":{"type":"boolean"}},"required":["id","typeName","label","tenantId","isSystem"],"additionalProperties":false,"nullable":true},"properties":{"type":"object","additionalProperties":true}},"required":["state","detection","appliedConfig","typeDefinition","properties"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/network-configs":{"get":{"summary":"List geo network configs","tags":["Geo-Location"],"description":"List tenant geo network configs and the available tenant/system type definitions used to validate their properties payload.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"configs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"typeDefinitionId":{"type":"string","format":"uuid"},"countryCodes":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2,3}$"}},"properties":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true}},"required":["id","tenantId","name","description","isDefault","typeDefinitionId","countryCodes","properties","createdAt","updatedAt","createdBy"],"additionalProperties":false}},"availableTypeDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"typeName":{"type":"string"},"label":{"type":"string"},"tenantId":{"type":"string","format":"uuid"},"isSystem":{"type":"boolean"}},"required":["id","typeName","label","tenantId","isSystem"],"additionalProperties":false}}},"required":["configs","availableTypeDefinitions"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create a geo network config","tags":["Geo-Location"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"typeDefinitionId":{"type":"string","format":"uuid","nullable":true},"properties":{"type":"object","additionalProperties":true},"countryCodes":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2,3}$"}}},"required":["name"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"typeDefinitionId":{"type":"string","format":"uuid"},"countryCodes":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2,3}$"}},"properties":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true}},"required":["id","tenantId","name","description","isDefault","typeDefinitionId","countryCodes","properties","createdAt","updatedAt","createdBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/network-configs/{configId}":{"patch":{"summary":"Update a geo network config","tags":["Geo-Location"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"typeDefinitionId":{"type":"string","format":"uuid","nullable":true},"properties":{"type":"object","additionalProperties":true},"countryCodes":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2,3}$"}}},"required":["name"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"configId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"typeDefinitionId":{"type":"string","format":"uuid"},"countryCodes":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2,3}$"}},"properties":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true}},"required":["id","tenantId","name","description","isDefault","typeDefinitionId","countryCodes","properties","createdAt","updatedAt","createdBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a geo network config","tags":["Geo-Location"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"configId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/geocode":{"post":{"summary":"Geocode an address","tags":["Geo-Location"],"description":"Convert a freeform or structured address into coordinates and tenant-formatted address details.","requestBody":{"content":{"application/json":{"schema":{"type":"object","anyOf":[{"required":["address"]},{"required":["structured"]}],"properties":{"address":{"type":"string","minLength":1},"locale":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"country":{"type":"string","pattern":"^[A-Z]{2,3}$"},"structured":{"type":"object","properties":{"street":{"type":"string"},"house_number":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"formatted_address":{"type":"object","properties":{"street":{"type":"string"},"house_number":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"}}},"display_name":{"type":"string"},"confidence":{"type":"number"},"provider":{"type":"string"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/reverse":{"post":{"summary":"Reverse geocode coordinates","tags":["Geo-Location"],"description":"Convert latitude and longitude into a tenant-formatted address for the requested locale.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"locale":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"zoom":{"type":"number","minimum":1,"maximum":18}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"formatted_address":{"type":"object","properties":{"street":{"type":"string"},"house_number":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"}}},"display_name":{"type":"string"},"provider":{"type":"string"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/autocomplete":{"get":{"summary":"Autocomplete addresses","tags":["Geo-Location"],"description":"Return tenant-formatted address suggestions with coordinates for search and selection flows.","parameters":[{"schema":{"type":"string","minLength":3},"in":"query","name":"q","required":true},{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"locale","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2,3}$"},"in":"query","name":"country","required":false},{"schema":{"type":"number","minimum":1,"maximum":50},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","properties":{"display_name":{"type":"string"},"formatted_display_name":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"type":{"type":"string"},"importance":{"type":"number"},"formatted_address":{"type":"object","properties":{"street":{"type":"string"},"house_number":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"}}}}}},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/config":{"get":{"summary":"Get geo display config","tags":["Geo-Location"],"description":"Return the effective geo display configuration for one locale and optional format type.","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"locale","required":true},{"schema":{"type":"string","enum":["local","international"]},"in":"query","name":"format_type","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"locale":{"type":"string"},"format_type":{"type":"string","enum":["local","international"]},"address_template":{"type":"string"},"component_order":{"type":"array","items":{"type":"string"}},"separator":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"tags":["Geo-Location"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["locale","format_type","address_template","component_order"],"properties":{"locale":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"format_type":{"type":"string","enum":["local","international"]},"address_template":{"type":"string","minLength":1},"component_order":{"type":"array","items":{"type":"string"},"minItems":1},"separator":{"type":"string"}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"locale":{"type":"string"},"format_type":{"type":"string","enum":["local","international"]},"address_template":{"type":"string"},"component_order":{"type":"array","items":{"type":"string"}},"separator":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete geo display config","tags":["Geo-Location"],"description":"Delete a display configuration for the current tenant","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"},"in":"query","name":"locale","required":true},{"schema":{"type":"string","enum":["local","international"]},"in":"query","name":"format_type","required":false}],"responses":{"204":{"description":"Successfully deleted"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/geo/configs":{"get":{"summary":"Get geo display configs","tags":["Geo-Location"],"description":"Return geo display configurations for multiple locales in one call.","parameters":[{"schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?(,[a-z]{2}(-[A-Z]{2})?)*$"},"in":"query","name":"locales","required":false,"description":"Comma-separated list of locale codes (e.g., \"de,en,fr\")"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"locale":{"type":"string"},"format_type":{"type":"string","enum":["local","international"]},"address_template":{"type":"string"},"component_order":{"type":"array","items":{"type":"string"}},"separator":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","tenantId","locale","format_type","address_template","component_order","separator","created_at","updated_at"]},"description":"Map of locale codes to config objects"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/app-accounts/":{"get":{"summary":"List application accounts","tags":["Application Accounts"],"description":"Retrieve all application accounts configured for the authenticated tenant.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"auth_user_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string"},"email":{"type":"string","format":"email"},"description":{"type":"string","nullable":true},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}}},"status":{"type":"string","enum":["active","suspended","revoked"]},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"created_by":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","email","permissions","status","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create application account","tags":["Application Accounts"],"description":"Create a new app account with optional permission configuration","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","email","password"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email"},"description":{"type":"string","maxLength":500},"password":{"type":"string","minLength":12,"description":"Minimum 12 characters"},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}},"description":"Optional permission configuration for this app account"},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"auth_user_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string"},"email":{"type":"string","format":"email"},"description":{"type":"string","nullable":true},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}}},"status":{"type":"string","enum":["active","suspended","revoked"]},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"created_by":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","email","permissions","status","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/app-accounts/{id}":{"get":{"summary":"Get application account details","tags":["Application Accounts"],"description":"Retrieve a specific application account with its current configuration and status.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"auth_user_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string"},"email":{"type":"string","format":"email"},"description":{"type":"string","nullable":true},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}}},"status":{"type":"string","enum":["active","suspended","revoked"]},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"created_by":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","email","permissions","status","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update application account","tags":["Application Accounts"],"description":"Update app account details including permissions","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}}},"status":{"type":"string","enum":["active","suspended","revoked"]},"expires_at":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"auth_user_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string"},"email":{"type":"string","format":"email"},"description":{"type":"string","nullable":true},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}}},"status":{"type":"string","enum":["active","suspended","revoked"]},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"created_by":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","email","permissions","status","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"tags":["Application Accounts"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/app-accounts/{id}/regenerate-password":{"post":{"tags":["Application Accounts"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"password":{"type":"string"}},"required":["password"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/app-accounts/{id}/set-password":{"post":{"tags":["Application Accounts"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"}},"required":["password"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}},"required":["data"],"additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/app-accounts/{id}/usage-stats":{"get":{"summary":"Get application account usage statistics","tags":["Application Accounts"],"description":"Retrieve usage metrics and activity statistics for a specific application account.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}},"required":["data"],"additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/":{"get":{"summary":"List tags","tags":["Tags"],"description":"List tags with optional search","parameters":[{"schema":{"type":"string"},"in":"query","name":"query","required":false,"description":"Search term (prefix or contains)"},{"schema":{"type":"string"},"in":"query","name":"category_key","required":false,"description":"Filter by linked category key"},{"schema":{"type":"string"},"in":"query","name":"preferredLanguage","required":false,"description":"Locale code for localized responses (e.g., de, en, fr, it)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_after","required":false,"description":"Filter by updated_at >= ISO 8601 date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_before","required":false,"description":"Filter by updated_at <= ISO 8601 date"},{"schema":{"type":"boolean"},"in":"query","name":"include_total","required":false,"description":"If true, include an exact total count"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Localized display name (preferred language with base-language fallback)"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Localized category summaries linked to the tag"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"returnedCount":{"type":"number"},"total":{"type":"number"}},"required":["data","returnedCount"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/{id}":{"get":{"summary":"Get tag","tags":["Tags"],"description":"Get tag by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"patch":{"summary":"Update tag","tags":["Tags"],"description":"Update tag base content, curated mode, and category assignments","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string","minLength":1,"maxLength":100,"description":"Base-language tag name"},"persistent":{"type":"boolean","description":"Curated/persistent mode"},"category_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete tag","tags":["Tags"],"description":"Delete tag (admin only)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Tag deleted successfully"}}}},"/api/v1/secure/taxonomy/tags/{id}/categories":{"patch":{"summary":"Replace tag categories","tags":["Tags"],"description":"Replace the category assignments of a tag","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["category_ids"],"properties":{"category_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/bulk-categories":{"post":{"summary":"Bulk modify tag categories","tags":["Tags"],"description":"Add, remove, or clear categories for multiple tags","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tag_ids","action"],"properties":{"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100},"action":{"type":"string","enum":["add","remove","clear"]},"category_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/link":{"post":{"summary":"Link tag to entity","tags":["Tags"],"description":"Link tag to entity (implicit tag creation)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tag_name","entity_type","entity_id"],"properties":{"tag_name":{"type":"string","minLength":1,"maxLength":100},"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tag_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tag_id","entity_type","entity_id","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/link/bulk":{"post":{"summary":"Bulk link tags","tags":["Tags"],"description":"Link multiple tags to entity at once","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tag_names","entity_type","entity_id"],"properties":{"tag_names":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":50},"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tag_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tag_id","entity_type","entity_id","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/{id}/unlink":{"delete":{"summary":"Unlink tag from entity","tags":["Tags"],"description":"Unlink tag from entity (auto-delete tag if no links remain)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["entity_type","entity_id"],"properties":{"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Tag unlinked successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/entity":{"get":{"summary":"List entity tags","tags":["Tags"],"description":"Get all tags for an entity","parameters":[{"schema":{"type":"string","enum":["space","resource","tenant","group"]},"in":"query","name":"entity_type","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"entity_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/cloud":{"get":{"summary":"Get tag cloud","tags":["Tags"],"description":"Get tag cloud (most used tags)","parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid"},"tag_name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name"},"count":{"type":"number","description":"Usage count"}},"required":["tag_id","tag_name","display_name","count"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/{id}/entities":{"get":{"summary":"List tagged entities","tags":["Tags"],"description":"Get all entities tagged with this tag (reverse lookup filter)","parameters":[{"schema":{"type":"string","enum":["space","resource","tenant","group"]},"in":"query","name":"entity_type","required":false,"description":"Filter by entity type (optional)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tag ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tag_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","tag_id","entity_type","entity_id","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/curated":{"post":{"summary":"Create curated tag","tags":["Tags"],"description":"Create a persistent curated tag (tenant admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tag_name"],"properties":{"tag_name":{"type":"string","minLength":1,"maxLength":100,"description":"Tag name"},"group_id":{"type":"string","format":"uuid","description":"Group ID for group-owned tags (optional)"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/{id}/translations":{"patch":{"summary":"Update tag translations","tags":["Tags"],"description":"Update translations for a tag (all provided locales at once)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["locale","name"],"properties":{"locale":{"type":"string","minLength":2,"maxLength":5,"description":"Locale code (e.g., en, de, fr, it)"},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Translated tag name"}}}}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tag ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/{id}/upgrade":{"patch":{"summary":"Upgrade tag to persistent","tags":["Tags"],"description":"Upgrade a tag to persistent/curated status (tenant admin only)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Tag ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/cleanup":{"post":{"summary":"Cleanup unused tags","tags":["Tags"],"description":"Delete non-persistent tags with no entity links (tenant admin only)","responses":{"200":{"description":"Cleanup completed","content":{"application/json":{"schema":{"description":"Cleanup completed","type":"object","properties":{"data":{"type":"object","properties":{"deleted_count":{"type":"number","description":"Number of tags deleted"}}}}}}}}}}},"/api/v1/secure/taxonomy/tags/bulk-update":{"post":{"summary":"Bulk update tags","tags":["Tags"],"description":"Update multiple tags in one transaction (all or nothing)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["updates"],"properties":{"updates":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"Tag ID"},"persistent":{"type":"boolean","description":"Set persistent/curated status"}}}}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Normalized name (lowercase)"},"display_name":{"type":"string","description":"Display name in base language"},"language":{"type":"string","description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"sort_order":{"type":"number"}},"required":["id","key","name","language","sort_order"],"additionalProperties":false},"description":"Categories linked to the tag"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":"Additional-language name translations only; the base language stays in display_name and language"},"usage_count":{"type":"number","description":"Number of entities linked to this tag"},"persistent":{"type":"boolean","description":"If true, tag exists without entity links (curated tag)"},"owner_id":{"type":"string","format":"uuid","description":"Owner UUID (user or group)"},"owner_type":{"type":"string","enum":["user","group"],"description":"Owner type"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","display_name","language","categories","translations_i18n","usage_count","persistent","owner_id","owner_type","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/tags/export":{"get":{"summary":"Export tags","tags":["Tags"],"description":"Export tags to Excel/CSV/TSV","parameters":[{"schema":{"type":"string","enum":["xlsx","csv","tsv","json","json-schema"],"default":"xlsx"},"in":"query","name":"format","required":false,"description":"Export file format (xlsx, csv, tsv)"},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeExample","required":false,"description":"Include example row if data is empty"},{"schema":{"type":"number","minimum":1,"maximum":10000,"default":10000},"in":"query","name":"limit","required":false,"description":"Maximum number of rows to export"},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Offset for pagination"}],"responses":{"200":{"description":"Binary file download","content":{"application/json":{"schema":{"description":"Binary file download","type":"string","format":"binary"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/taxonomy/tags/import":{"post":{"summary":"Import tags","tags":["Tags"],"description":"Import tags from Excel/CSV/TSV file","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether import completed without critical errors"},"dryRun":{"type":"boolean","description":"Whether this was a validation-only dry run"},"entityType":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"],"description":"Entity type that was imported"},"stats":{"type":"object","properties":{"created":{"type":"number","description":"Number of entities created"},"updated":{"type":"number","description":"Number of entities updated"},"skipped":{"type":"number","description":"Number of entities skipped (merge strategy)"},"duplicates":{"type":"number","description":"Number of duplicate entries detected"},"errors":{"type":"number","description":"Number of rows with errors"}},"required":["created","updated","skipped","duplicates","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","description":"Row number (1-based, including header)"},"column":{"type":"string","description":"Column name where error occurred"},"value":{"type":"string","description":"Value that caused the error"},"identifier":{"type":"string","description":"Entity identifier (name, key, id)"},"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["INVALID_FORMAT","REQUIRED_FIELD","INVALID_UUID","DUPLICATE_ENTRY","REFERENCE_NOT_FOUND","VALIDATION_ERROR","IMPORT_ERROR","FILE_ERROR"]}},"required":["identifier","message","code"],"additionalProperties":false},"description":"Detailed error information per row"},"processedRows":{"type":"number","description":"Total number of rows processed"},"totalRows":{"type":"number","description":"Total number of rows in file"}},"required":["success","dryRun","entityType","stats","warnings","errors"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/taxonomy/categories/":{"get":{"summary":"List categories","tags":["Categories"],"description":"List categories with optional filters (flat listing)","parameters":[{"schema":{"type":["string","null"]},"in":"query","name":"parent_id","required":false,"description":"Filter by parent (null for root)"},{"schema":{"type":["string","null"]},"in":"query","name":"filter_id","required":false,"description":"Filter by filter_id (null for any, or specific type)"},{"schema":{"type":"string"},"in":"query","name":"query","required":false,"description":"Search in category key, name, or description"},{"schema":{"type":"string"},"in":"query","name":"preferredLanguage","required":false,"description":"Locale code for localized responses (e.g., de, en, fr, it)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_after","required":false,"description":"Filter by updated_at >= ISO 8601 date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_before","required":false,"description":"Filter by updated_at <= ISO 8601 date"},{"schema":{"type":"boolean"},"in":"query","name":"include_total","required":false,"description":"If true, include an exact total count"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"level":{"type":"number"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string","description":"Localized name (preferred language with EN fallback)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Localized description"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code"},"usage_count":{"type":"number"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","usage_count","created_at","updated_at"],"additionalProperties":false}},"returnedCount":{"type":"number"},"total":{"type":"number"}},"required":["data","returnedCount"],"additionalProperties":false}}}}}},"post":{"summary":"Create category","tags":["Categories"],"description":"Create category (admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","name"],"properties":{"key":{"type":"string","pattern":"^[a-z0-9-]+$","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Base language name"},"language":{"type":"string","minLength":2,"maxLength":5,"description":"Base language ISO 639-1 code; defaults to tenant default_language"},"description":{"type":["string","null"],"description":"Base language description"},"parent_id":{"type":["string","null"],"format":"uuid"},"filter_id":{"type":["string","null"],"minLength":1,"maxLength":100},"sort_order":{"type":"number","minimum":0,"description":"Manual sibling sort order override"},"translations_i18n":{"type":"object","description":"Additional language translations ONLY — must NOT include the base language","additionalProperties":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string"}}}}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Parent category ID (null for root)"},"key":{"type":"string","description":"URL-safe identifier"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional filter for type-specific categories"},"level":{"type":"number","description":"Hierarchy depth (0 = root)"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"description":"Translations for additional languages only (excludes the base language)"},"usage_count":{"type":"number","description":"Number of entities linked to this category"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","translations_i18n","usage_count","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/tree":{"get":{"summary":"Get category tree","tags":["Categories"],"description":"Get category tree (hierarchical listing)","parameters":[{"schema":{"type":["string","null"]},"in":"query","name":"parent_id","required":false,"description":"Root parent (null for full tree)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"level":{"type":"number"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"description":"Translations for additional languages only (excludes the base language)"},"usage_count":{"type":"number"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"children":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Recursive category structure"},"description":"Child categories (hierarchical)"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","translations_i18n","usage_count","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/{id}/sort-order/move":{"post":{"summary":"Move category sort order","tags":["Categories"],"description":"Move a category up or down within its sibling list","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["direction"],"properties":{"direction":{"type":"string","enum":["up","down"]}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Parent category ID (null for root)"},"key":{"type":"string","description":"URL-safe identifier"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional filter for type-specific categories"},"level":{"type":"number","description":"Hierarchy depth (0 = root)"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"description":"Translations for additional languages only (excludes the base language)"},"usage_count":{"type":"number","description":"Number of entities linked to this category"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","translations_i18n","usage_count","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/sort-order/reset":{"post":{"summary":"Reset category sort order","tags":["Categories"],"description":"Reset category sibling ordering by name or creation date","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["strategy"],"properties":{"strategy":{"type":"string","enum":["name","created_at"]}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"updated_count":{"type":"number"},"strategy":{"type":"string","enum":["name","created_at"]}},"required":["updated_count","strategy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/{id}":{"get":{"summary":"Get category","tags":["Categories"],"description":"Get category by ID","parameters":[{"schema":{"type":"string"},"in":"query","name":"preferredLanguage","required":false,"description":"Locale code for localized responses (e.g., de, en, fr, it)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Parent category ID (null for root)"},"key":{"type":"string","description":"URL-safe identifier"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional filter for type-specific categories"},"level":{"type":"number","description":"Hierarchy depth (0 = root)"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"description":"Translations for additional languages only (excludes the base language)"},"usage_count":{"type":"number","description":"Number of entities linked to this category"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","translations_i18n","usage_count","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"patch":{"summary":"Update category","tags":["Categories"],"description":"Update category (admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9-]+$","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Base language name"},"language":{"type":"string","minLength":2,"maxLength":5,"description":"Base language ISO 639-1 code"},"description":{"type":["string","null"],"description":"Base language description"},"parent_id":{"type":["string","null"],"format":"uuid"},"filter_id":{"type":["string","null"],"minLength":1,"maxLength":100},"sort_order":{"type":"number","minimum":0,"description":"Manual sibling sort order override"},"translations_i18n":{"type":"object","description":"Additional language translations ONLY — must NOT include the base language","additionalProperties":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string"}}}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Parent category ID (null for root)"},"key":{"type":"string","description":"URL-safe identifier"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional filter for type-specific categories"},"level":{"type":"number","description":"Hierarchy depth (0 = root)"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string","description":"Display name in base language"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description in base language"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code (e.g., en, de, fr, it)"},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"description":"Translations for additional languages only (excludes the base language)"},"usage_count":{"type":"number","description":"Number of entities linked to this category"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","translations_i18n","usage_count","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete category","tags":["Categories"],"description":"Delete category (admin only, requires replacement if links exist)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"replacement_category_id":{"type":"string","format":"uuid"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Category deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/{id}/i18n":{"patch":{"summary":"Upsert category translation","tags":["Categories"],"description":"Upsert category translation (admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["locale","name"],"properties":{"locale":{"type":"string","enum":["de","en","fr","it"]},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string"}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"categoryId":{"type":"string","format":"uuid"},"locale":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"type":"string","format":"date-time"}},"required":["tenantId","categoryId","locale","name","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/{id}/link":{"post":{"summary":"Link category to entity","tags":["Categories"],"description":"Link category to entity","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["entity_type","entity_id"],"properties":{"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"},"preferredLanguage":{"type":"string","description":"Locale code for localized responses (e.g., de, en, fr, it)"}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"categoryId":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["space","resource","tenant","group"]},"entityId":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","categoryId","entityType","entityId","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/{id}/unlink":{"delete":{"summary":"Unlink category from entity","tags":["Categories"],"description":"Unlink category from entity","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["entity_type","entity_id"],"properties":{"entity_type":{"type":"string","enum":["space","resource","tenant","group"]},"entity_id":{"type":"string","format":"uuid"}}}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Category unlinked successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/entity":{"get":{"summary":"List entity categories","tags":["Categories"],"description":"Get all categories for an entity","parameters":[{"schema":{"type":"string","enum":["space","resource","tenant","group"]},"in":"query","name":"entity_type","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"entity_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string"},"filter_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"level":{"type":"number"},"sort_order":{"type":"number","description":"Manual sibling ordering within the same parent"},"name":{"type":"string","description":"Localized name (preferred language with EN fallback)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Localized description"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 639-1 language code"},"usage_count":{"type":"number"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","key","filter_id","level","sort_order","name","usage_count","created_at","updated_at"],"additionalProperties":false}},"returnedCount":{"type":"number"},"total":{"type":"number"}},"required":["data","returnedCount"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/{id}/entities":{"get":{"summary":"List categorized entities","tags":["Categories"],"description":"Get all entities with this category (reverse lookup filter)","parameters":[{"schema":{"type":"string","enum":["space","resource","tenant","group"]},"in":"query","name":"entity_type","required":false,"description":"Filter by entity type (optional)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Category ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"categoryId":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["space","resource","tenant","group"]},"entityId":{"type":"string","format":"uuid"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","categoryId","entityType","entityId","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/secure/taxonomy/categories/export":{"get":{"summary":"Export categories","tags":["Categories"],"description":"Export categories to Excel/CSV/TSV","parameters":[{"schema":{"type":"string","enum":["xlsx","csv","tsv","json","json-schema"],"default":"xlsx"},"in":"query","name":"format","required":false,"description":"Export file format (xlsx, csv, tsv)"},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeExample","required":false,"description":"Include example row if data is empty"},{"schema":{"type":"number","minimum":1,"maximum":10000,"default":10000},"in":"query","name":"limit","required":false,"description":"Maximum number of rows to export"},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Offset for pagination"}],"responses":{"200":{"description":"Binary file download","content":{"application/json":{"schema":{"description":"Binary file download","type":"string","format":"binary"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/taxonomy/categories/import":{"post":{"summary":"Import categories","tags":["Categories"],"description":"Import categories from Excel/CSV/TSV file","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether import completed without critical errors"},"dryRun":{"type":"boolean","description":"Whether this was a validation-only dry run"},"entityType":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"],"description":"Entity type that was imported"},"stats":{"type":"object","properties":{"created":{"type":"number","description":"Number of entities created"},"updated":{"type":"number","description":"Number of entities updated"},"skipped":{"type":"number","description":"Number of entities skipped (merge strategy)"},"duplicates":{"type":"number","description":"Number of duplicate entries detected"},"errors":{"type":"number","description":"Number of rows with errors"}},"required":["created","updated","skipped","duplicates","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","description":"Row number (1-based, including header)"},"column":{"type":"string","description":"Column name where error occurred"},"value":{"type":"string","description":"Value that caused the error"},"identifier":{"type":"string","description":"Entity identifier (name, key, id)"},"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["INVALID_FORMAT","REQUIRED_FIELD","INVALID_UUID","DUPLICATE_ENTRY","REFERENCE_NOT_FOUND","VALIDATION_ERROR","IMPORT_ERROR","FILE_ERROR"]}},"required":["identifier","message","code"],"additionalProperties":false},"description":"Detailed error information per row"},"processedRows":{"type":"number","description":"Total number of rows processed"},"totalRows":{"type":"number","description":"Total number of rows in file"}},"required":["success","dryRun","entityType","stats","warnings","errors"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/type-definitions/":{"get":{"summary":"List type definitions","tags":["Type Definitions"],"description":"Retrieve type definitions with optional filtering by target entity type, type name, and system-type visibility.","parameters":[{"schema":{"type":"string","enum":["space","resource","calendar","user","tenant"]},"in":"query","name":"appliesTo","required":false,"description":"Filter by entity type"},{"schema":{"type":"string"},"in":"query","name":"typeName","required":false,"description":"Filter by type name (exact match)"},{"schema":{"type":"boolean"},"in":"query","name":"showSystemTypes","required":false,"description":"true = show all types (own tenant + system types), false/null (DEFAULT) = show only own tenant types"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"tags":["Type Definitions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","label","schemaDefinition"],"properties":{"name":{"type":"string","description":"Unique type name (kebab-case recommended)","pattern":"^[a-z0-9-]+$","minLength":2,"maxLength":100},"label":{"type":"string","description":"Human-readable label","minLength":2,"maxLength":255},"description":{"type":"string","description":"Optional description of the type","maxLength":1000},"category":{"type":"string","description":"Category hint used to infer appliesTo when appliesTo is omitted","maxLength":100},"appliesTo":{"type":"string","enum":["space","resource","calendar","user","tenant"],"description":"Explicit entity type this definition applies to"},"schemaDefinition":{"type":"object","description":"JSON Schema for validating settings","required":["properties"],"properties":{"properties":{"type":"object","additionalProperties":true},"required":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/type-definitions/{id}":{"get":{"summary":"Get type definition details","tags":["Type Definitions"],"description":"Retrieve a specific type definition and its schema details by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"tags":["Type Definitions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":2,"maxLength":255},"description":{"type":"string","maxLength":1000},"is_active":{"type":"boolean"},"schemaDefinition":{"type":"object","properties":{"properties":{"type":"object","additionalProperties":true},"required":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"tags":["Type Definitions"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/type-definitions/{id}/export":{"get":{"summary":"Export type definition","tags":["Type Definitions"],"description":"Export a single type definition as JSON","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string","description":"Type definition name (kebab-case)"},"label":{"type":"string","description":"Human-readable label"},"description":{"type":["null","string"],"description":"Optional description"},"appliesTo":{"type":"string","enum":["space","resource","calendar","user","tenant"],"description":"Entity type this definition applies to"},"schemaDefinition":{"type":"object","description":"Canonical nested schema definition for the type","required":["properties"],"properties":{"properties":{"type":"object","additionalProperties":true},"required":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"properties":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"},"description":{"type":["null","string"]},"isMandatory":{"type":"boolean"},"defaultValue":{"type":"object","nullable":true,"additionalProperties":true},"validationRules":{"type":"object","nullable":true,"additionalProperties":true},"displayOrder":{"type":"integer"}},"required":["name","type","displayName","isMandatory","displayOrder"]},"description":"Property schemas for this type definition"}},"required":["name","label","appliesTo","properties"]}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/type-definitions/export":{"get":{"summary":"Export type definitions","tags":["Type Definitions"],"description":"Export all type definitions for the tenant as JSON bundle","parameters":[{"schema":{"type":"string","enum":["space","resource","calendar","user","tenant"]},"in":"query","name":"appliesTo","required":false,"description":"Filter by entity type"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"version":{"type":"string","description":"Bundle version (e.g., \"1.0\")"},"exportedAt":{"type":"string","format":"date-time"},"source":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantSlug":{"type":"string"}},"required":["tenantId"]},"typeDefinitions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Type definition name (kebab-case)"},"label":{"type":"string","description":"Human-readable label"},"description":{"type":["null","string"],"description":"Optional description"},"appliesTo":{"type":"string","enum":["space","resource","calendar","user","tenant"],"description":"Entity type this definition applies to"},"schemaDefinition":{"type":"object","description":"Canonical nested schema definition for the type","required":["properties"],"properties":{"properties":{"type":"object","additionalProperties":true},"required":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"properties":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"},"description":{"type":["null","string"]},"isMandatory":{"type":"boolean"},"defaultValue":{"type":"object","nullable":true,"additionalProperties":true},"validationRules":{"type":"object","nullable":true,"additionalProperties":true},"displayOrder":{"type":"integer"}},"required":["name","type","displayName","isMandatory","displayOrder"]},"description":"Property schemas for this type definition"}},"required":["name","label","appliesTo","properties"]}}},"required":["version","exportedAt","source","typeDefinitions"]}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/type-definitions/import":{"post":{"summary":"Import type definitions","tags":["Type Definitions"],"description":"Import type definitions from JSON. Supports individual type definitions or bundle format.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"typeDefinitions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Type definition name (kebab-case, validated in service)"},"label":{"type":"string","description":"Human-readable label"},"description":{"type":["string","null"]},"appliesTo":{"type":"string","enum":["space","resource","calendar","user","tenant"]},"properties":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"},"description":{"type":["string","null"]},"isMandatory":{"type":"boolean"},"defaultValue":{"type":"object","nullable":true,"additionalProperties":true},"validationRules":{"type":"object","nullable":true,"additionalProperties":true},"displayOrder":{"type":"integer"}},"required":["name","type","displayName"]}}},"required":["name","label","appliesTo"]}},"options":{"type":"object","properties":{"mergeStrategy":{"type":"string","enum":["skip","replace","merge"],"default":"skip","description":"How to handle existing type definitions: skip (keep existing), replace (overwrite), merge (update only empty fields)"},"dryRun":{"type":"boolean","default":false,"description":"If true, validate without saving"}}}},"required":["typeDefinitions"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"dryRun":{"type":"boolean"},"stats":{"type":"object","properties":{"created":{"type":"number"},"updated":{"type":"number"},"skipped":{"type":"number"},"duplicates":{"type":"number"},"errors":{"type":"number"}}},"warnings":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","description":"Type definition index in input array"},"identifier":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/type-definitions/export/excel":{"get":{"summary":"Export type definitions as spreadsheet","tags":["Type Definitions"],"description":"Export type definitions to Excel/CSV/TSV format (shared system)","parameters":[{"schema":{"type":"string","enum":["xlsx","csv","tsv"],"default":"xlsx"},"in":"query","name":"format","required":false},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeExample","required":false},{"schema":{"type":"number","minimum":1,"maximum":10000,"default":10000},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Binary file download (xlsx, csv, or tsv)","content":{"application/json":{"schema":{"description":"Binary file download (xlsx, csv, or tsv)","type":"string","format":"binary"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/type-definitions/import/excel":{"post":{"summary":"Import type definitions from spreadsheet","tags":["Type Definitions"],"description":"Import type definitions from Excel/CSV/TSV file (shared system)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"dryRun":{"type":"boolean"},"stats":{"type":"object","properties":{"created":{"type":"number"},"updated":{"type":"number"},"skipped":{"type":"number"},"duplicates":{"type":"number"},"errors":{"type":"number"}}},"warnings":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","description":"Type definition index in input array"},"identifier":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}}}}}}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/features/":{"get":{"summary":"List features","tags":["Features"],"description":"List all features for current tenant with their status","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["feature_key","enabled","config","definition"],"properties":{"feature_key":{"type":"string"},"enabled":{"type":"boolean"},"config":{"type":"object","additionalProperties":true},"definition":{"type":"object","required":["key","name","description","category","dependencies","defaultEnabled"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["core","premium","experimental"]},"dependencies":{"type":"array","items":{"type":"string"}},"defaultEnabled":{"type":"boolean"}}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/features/{key}":{"get":{"summary":"Get feature status","tags":["Features"],"description":"Get status of a specific feature","parameters":[{"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"in":"path","name":"key","required":true,"description":"Feature key (e.g., calendar, billing)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["feature_key","enabled","config","definition"],"properties":{"feature_key":{"type":"string"},"enabled":{"type":"boolean"},"config":{"type":"object","additionalProperties":true},"definition":{"type":"object","required":["key","name","description","category","dependencies","defaultEnabled"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["core","premium","experimental"]},"dependencies":{"type":"array","items":{"type":"string"}},"defaultEnabled":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update feature status","tags":["Features"],"description":"Enable or disable a feature (tenant or system admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean","description":"Whether to enable or disable the feature"},"config":{"type":"object","additionalProperties":true,"description":"Feature-specific configuration"},"changed_reason":{"type":"string","description":"Reason for the change (audit trail)"}}}}},"required":true},"parameters":[{"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"in":"path","name":"key","required":true,"description":"Feature key"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["feature_key","enabled","config","definition"],"properties":{"feature_key":{"type":"string"},"enabled":{"type":"boolean"},"config":{"type":"object","additionalProperties":true},"definition":{"type":"object","required":["key","name","description","category","dependencies","defaultEnabled"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["core","premium","experimental"]},"dependencies":{"type":"array","items":{"type":"string"}},"defaultEnabled":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/features/bulk":{"post":{"summary":"Bulk update features","tags":["Features"],"description":"Bulk enable/disable features (tenant or system admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["updates"],"properties":{"updates":{"type":"array","items":{"type":"object","required":["feature_key","enabled"],"properties":{"feature_key":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"enabled":{"type":"boolean"},"config":{"type":"object","additionalProperties":true},"changed_reason":{"type":"string"}}}}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["feature_key","enabled","config","definition"],"properties":{"feature_key":{"type":"string"},"enabled":{"type":"boolean"},"config":{"type":"object","additionalProperties":true},"definition":{"type":"object","required":["key","name","description","category","dependencies","defaultEnabled"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["core","premium","experimental"]},"dependencies":{"type":"array","items":{"type":"string"}},"defaultEnabled":{"type":"boolean"}}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/features/catalog":{"get":{"summary":"Get feature catalog","tags":["Features"],"description":"Get catalog of all available features (system admin only)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["key","name","description","category","dependencies","defaultEnabled"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["core","premium","experimental"]},"dependencies":{"type":"array","items":{"type":"string"}},"defaultEnabled":{"type":"boolean"}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/api-keys/":{"get":{"summary":"List API keys","tags":["API Keys"],"description":"Retrieve all API keys configured for the authenticated tenant.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"API key unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this key belongs to"},"key_uuid":{"type":"string","format":"uuid","description":"Public part of the API key (shown in preview)"},"key_preview":{"type":"string","description":"Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"},"name":{"type":"string","description":"Human-readable name for the API key"},"description":{"type":["null","string"],"description":"Optional description of key purpose"},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}},"description":"Fine-grained access permissions for programmatic access"},"mcp_write_enabled":{"type":"boolean","description":"Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"},"enabled":{"type":"boolean","description":"Whether the API key is currently active"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Optional expiration timestamp (ISO 8601)"},"ip_whitelist":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"},"device_fingerprint":{"type":["null","string"],"description":"Optional device fingerprint for mobile attestation"},"last_used_at":{"type":["null","string"],"format":"date-time","description":"Timestamp of last successful authentication (ISO 8601)"},"last_used_ip":{"type":["null","string"],"description":"IP address of last successful authentication"},"request_count":{"type":"integer","description":"Total number of requests made with this key"},"created_by":{"type":["null","string"],"format":"uuid","description":"User who created this key"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","key_uuid","key_preview","name","permissions","mcp_write_enabled","enabled","request_count","created_at","updated_at"],"additionalProperties":false},"description":"Array of API key objects"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create API key","tags":["API Keys"],"description":"Create a new API key with permission configuration. Returns the full key (only shown once!)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable name for the API key (1-100 chars)"},"description":{"type":"string","maxLength":500,"description":"Optional description of key purpose (max 500 chars)"},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}},"description":"Permission structure for programmatic access (app accounts & API keys).\n\n**Permission Templates:**\n- `READ_ONLY`: Read-only access to resources, spaces, tags, categories, type definitions, and geo services\n- `ASSET_TRACKER`: Update resource location and status (for tracking apps)\n- `BOOKING_SYSTEM`: Full resource management with calendar access\n- `FULL_ACCESS`: Complete access to all services\n- `MCP_DEVELOPER`: Full tenant-admin level access for MCP tool usage and app development\n\n**Permission Sections:**\n- `resources`: Access to resource CRUD operations and specific properties\n- `spaces`: Access to space management\n- `tags`: Access to tag lookup data for search and selection\n- `categories`: Access to category lookup data for search and selection\n- `typeDefinitions`: Access to type definition lookup data for app forms and filters\n- `feedbacks`: Access to ratings, reviews, and aggregate feedback data\n- `qrCodes`: Access to QR code lookup, management, deletion, and assignment/linking\n- `geo`: Geocoding and reverse geocoding services\n- `calendar`: Calendar and availability services\n- `users`: User information access\n\n**Property-Level Access:**\nThe `resources.properties` array controls field-level access:\n- Empty array `[]` = Access to ALL properties\n- Specific list `[\"currentLocation\", \"status\"]` = Only these properties can be read/written\n\n**Example Usage:**\n```json\n{\n  \"resources\": {\n    \"read\": true,\n    \"write\": true,\n    \"delete\": false,\n    \"properties\": [\"currentLocation\", \"status\"]\n  },\n  \"spaces\": { \"read\": true, \"write\": false, \"delete\": false },\n  \"tags\": { \"read\": true },\n  \"categories\": { \"read\": true },\n  \"typeDefinitions\": { \"read\": true },\n  \"feedbacks\": { \"read\": true },\n  \"qrCodes\": { \"read\": true, \"write\": false, \"delete\": false, \"assign\": false },\n  \"geo\": { \"geocode\": true, \"reverse_geocode\": true },\n  \"calendar\": { \"free_busy\": false, \"events\": false },\n  \"users\": { \"read\": false }\n}\n```"},"mcp_write_enabled":{"type":"boolean","description":"Enable MCP mutating operations for this key (default: false)"},"expires_at":{"type":"string","format":"date-time","description":"Optional expiration timestamp (ISO 8601)"},"ip_whitelist":{"type":"array","items":{"type":"string"},"description":"Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\", \"10.0.0.1\"])"},"device_fingerprint":{"type":"string","description":"Optional device fingerprint for mobile attestation"}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"API key unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this key belongs to"},"key_uuid":{"type":"string","format":"uuid","description":"Public part of the API key (shown in preview)"},"key_preview":{"type":"string","description":"Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"},"name":{"type":"string","description":"Human-readable name for the API key"},"description":{"type":["null","string"],"description":"Optional description of key purpose"},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}},"description":"Fine-grained access permissions for programmatic access"},"mcp_write_enabled":{"type":"boolean","description":"Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"},"enabled":{"type":"boolean","description":"Whether the API key is currently active"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Optional expiration timestamp (ISO 8601)"},"ip_whitelist":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"},"device_fingerprint":{"type":["null","string"],"description":"Optional device fingerprint for mobile attestation"},"last_used_at":{"type":["null","string"],"format":"date-time","description":"Timestamp of last successful authentication (ISO 8601)"},"last_used_ip":{"type":["null","string"],"description":"IP address of last successful authentication"},"request_count":{"type":"integer","description":"Total number of requests made with this key"},"created_by":{"type":["null","string"],"format":"uuid","description":"User who created this key"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","key_uuid","key_preview","name","permissions","mcp_write_enabled","enabled","request_count","created_at","updated_at"],"additionalProperties":false},"fullKey":{"type":"string","description":"CRITICAL: Full API key (pve_sk_{uuid}_{secret}). Save immediately - shown only once!"},"message":{"type":"string","description":"Warning message to save the key securely"}},"required":["data","fullKey","message"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/api-keys/{id}":{"get":{"summary":"Get API key details","tags":["API Keys"],"description":"Retrieve configuration and status details for a specific API key.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"API key unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this key belongs to"},"key_uuid":{"type":"string","format":"uuid","description":"Public part of the API key (shown in preview)"},"key_preview":{"type":"string","description":"Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"},"name":{"type":"string","description":"Human-readable name for the API key"},"description":{"type":["null","string"],"description":"Optional description of key purpose"},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}},"description":"Fine-grained access permissions for programmatic access"},"mcp_write_enabled":{"type":"boolean","description":"Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"},"enabled":{"type":"boolean","description":"Whether the API key is currently active"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Optional expiration timestamp (ISO 8601)"},"ip_whitelist":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"},"device_fingerprint":{"type":["null","string"],"description":"Optional device fingerprint for mobile attestation"},"last_used_at":{"type":["null","string"],"format":"date-time","description":"Timestamp of last successful authentication (ISO 8601)"},"last_used_ip":{"type":["null","string"],"description":"IP address of last successful authentication"},"request_count":{"type":"integer","description":"Total number of requests made with this key"},"created_by":{"type":["null","string"],"format":"uuid","description":"User who created this key"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","key_uuid","key_preview","name","permissions","mcp_write_enabled","enabled","request_count","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"tags":["API Keys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Update API key name (1-100 chars)"},"description":{"type":"string","maxLength":500,"description":"Update description (max 500 chars)"},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}},"description":"Permission structure for programmatic access (app accounts & API keys).\n\n**Permission Templates:**\n- `READ_ONLY`: Read-only access to resources, spaces, tags, categories, type definitions, and geo services\n- `ASSET_TRACKER`: Update resource location and status (for tracking apps)\n- `BOOKING_SYSTEM`: Full resource management with calendar access\n- `FULL_ACCESS`: Complete access to all services\n- `MCP_DEVELOPER`: Full tenant-admin level access for MCP tool usage and app development\n\n**Permission Sections:**\n- `resources`: Access to resource CRUD operations and specific properties\n- `spaces`: Access to space management\n- `tags`: Access to tag lookup data for search and selection\n- `categories`: Access to category lookup data for search and selection\n- `typeDefinitions`: Access to type definition lookup data for app forms and filters\n- `feedbacks`: Access to ratings, reviews, and aggregate feedback data\n- `qrCodes`: Access to QR code lookup, management, deletion, and assignment/linking\n- `geo`: Geocoding and reverse geocoding services\n- `calendar`: Calendar and availability services\n- `users`: User information access\n\n**Property-Level Access:**\nThe `resources.properties` array controls field-level access:\n- Empty array `[]` = Access to ALL properties\n- Specific list `[\"currentLocation\", \"status\"]` = Only these properties can be read/written\n\n**Example Usage:**\n```json\n{\n  \"resources\": {\n    \"read\": true,\n    \"write\": true,\n    \"delete\": false,\n    \"properties\": [\"currentLocation\", \"status\"]\n  },\n  \"spaces\": { \"read\": true, \"write\": false, \"delete\": false },\n  \"tags\": { \"read\": true },\n  \"categories\": { \"read\": true },\n  \"typeDefinitions\": { \"read\": true },\n  \"feedbacks\": { \"read\": true },\n  \"qrCodes\": { \"read\": true, \"write\": false, \"delete\": false, \"assign\": false },\n  \"geo\": { \"geocode\": true, \"reverse_geocode\": true },\n  \"calendar\": { \"free_busy\": false, \"events\": false },\n  \"users\": { \"read\": false }\n}\n``` (partial update supported)"},"mcp_write_enabled":{"type":"boolean","description":"Enable or disable MCP mutating operations for this key"},"enabled":{"type":"boolean","description":"Enable or disable the API key (false immediately revokes access)"},"expires_at":{"type":["string","null"],"format":"date-time","description":"Update expiration timestamp (ISO 8601) or null to remove"},"ip_whitelist":{"type":["array","null"],"items":{"type":"string"},"description":"Update IP whitelist or null to remove restrictions"},"device_fingerprint":{"type":["string","null"],"description":"Update device fingerprint or null to remove"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"API key unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this key belongs to"},"key_uuid":{"type":"string","format":"uuid","description":"Public part of the API key (shown in preview)"},"key_preview":{"type":"string","description":"Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"},"name":{"type":"string","description":"Human-readable name for the API key"},"description":{"type":["null","string"],"description":"Optional description of key purpose"},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}},"description":"Fine-grained access permissions for programmatic access"},"mcp_write_enabled":{"type":"boolean","description":"Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"},"enabled":{"type":"boolean","description":"Whether the API key is currently active"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Optional expiration timestamp (ISO 8601)"},"ip_whitelist":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"},"device_fingerprint":{"type":["null","string"],"description":"Optional device fingerprint for mobile attestation"},"last_used_at":{"type":["null","string"],"format":"date-time","description":"Timestamp of last successful authentication (ISO 8601)"},"last_used_ip":{"type":["null","string"],"description":"IP address of last successful authentication"},"request_count":{"type":"integer","description":"Total number of requests made with this key"},"created_by":{"type":["null","string"],"format":"uuid","description":"User who created this key"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","key_uuid","key_preview","name","permissions","mcp_write_enabled","enabled","request_count","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"tags":["API Keys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"API key deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/api-keys/{id}/rotate":{"post":{"tags":["API Keys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"API key unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this key belongs to"},"key_uuid":{"type":"string","format":"uuid","description":"Public part of the API key (shown in preview)"},"key_preview":{"type":"string","description":"Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"},"name":{"type":"string","description":"Human-readable name for the API key"},"description":{"type":["null","string"],"description":"Optional description of key purpose"},"permissions":{"type":"object","additionalProperties":false,"properties":{"resources":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"properties":{"type":"array","items":{"type":"string"},"description":"Allowed property names. Empty array = all properties accessible"}}},"spaces":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"}}},"tags":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"categories":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"typeDefinitions":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"feedbacks":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}},"qrCodes":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"},"write":{"type":"boolean"},"delete":{"type":"boolean"},"assign":{"type":"boolean"}}},"geo":{"type":"object","additionalProperties":false,"properties":{"geocode":{"type":"boolean"},"reverse_geocode":{"type":"boolean"}}},"calendar":{"type":"object","additionalProperties":false,"properties":{"free_busy":{"type":"boolean"},"events":{"type":"boolean"}}},"users":{"type":"object","additionalProperties":false,"properties":{"read":{"type":"boolean"}}}},"description":"Fine-grained access permissions for programmatic access"},"mcp_write_enabled":{"type":"boolean","description":"Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"},"enabled":{"type":"boolean","description":"Whether the API key is currently active"},"expires_at":{"type":["null","string"],"format":"date-time","description":"Optional expiration timestamp (ISO 8601)"},"ip_whitelist":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"},"device_fingerprint":{"type":["null","string"],"description":"Optional device fingerprint for mobile attestation"},"last_used_at":{"type":["null","string"],"format":"date-time","description":"Timestamp of last successful authentication (ISO 8601)"},"last_used_ip":{"type":["null","string"],"description":"IP address of last successful authentication"},"request_count":{"type":"integer","description":"Total number of requests made with this key"},"created_by":{"type":["null","string"],"format":"uuid","description":"User who created this key"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","key_uuid","key_preview","name","permissions","mcp_write_enabled","enabled","request_count","created_at","updated_at"],"additionalProperties":false},"fullKey":{"type":"string","description":"CRITICAL: New full API key (pve_sk_{uuid}_{secret}). Save immediately - shown only once!"},"message":{"type":"string","description":"Warning message to save the new key securely"}},"required":["data","fullKey","message"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenant-domains/":{"get":{"summary":"List tenant domains","tags":["Tenant Domains"],"description":"Retrieve all custom domains configured for the authenticated tenant.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Domain configuration unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this domain belongs to"},"domain":{"type":"string","description":"Custom domain (e.g., api.wishtree.online)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api (platform API root, environment-specific target resolved by deployment)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Verification status: pending, verifying, verified, failed, expired"},"verification_token":{"type":["null","string"],"description":"Unique token for domain verification (32-char alphanumeric)"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"},"verified_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when domain was successfully verified (ISO 8601)"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"SSL certificate status: none, pending, issued, failed, expiring, expired"},"ssl_issued_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate was issued (ISO 8601)"},"ssl_expires_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate expires (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","domain","domain_type","status","verification_method","ssl_status","settings","created_at","updated_at"],"additionalProperties":false},"description":"Array of tenant domain objects"}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create tenant domain","tags":["Tenant Domains"],"description":"Create a new tenant domain configuration for white-label deployment","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["domain","domain_type"],"properties":{"domain":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$","description":"Custom domain (valid hostname format, no protocol, no path)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method (default: cname)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Domain configuration unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this domain belongs to"},"domain":{"type":"string","description":"Custom domain (e.g., api.wishtree.online)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api (platform API root, environment-specific target resolved by deployment)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Verification status: pending, verifying, verified, failed, expired"},"verification_token":{"type":["null","string"],"description":"Unique token for domain verification (32-char alphanumeric)"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"},"verified_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when domain was successfully verified (ISO 8601)"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"SSL certificate status: none, pending, issued, failed, expiring, expired"},"ssl_issued_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate was issued (ISO 8601)"},"ssl_expires_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate expires (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","domain","domain_type","status","verification_method","ssl_status","settings","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenant-domains/{id}":{"get":{"summary":"Get tenant domain details","tags":["Tenant Domains"],"description":"Retrieve configuration and verification status for a specific tenant domain.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Domain configuration unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this domain belongs to"},"domain":{"type":"string","description":"Custom domain (e.g., api.wishtree.online)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api (platform API root, environment-specific target resolved by deployment)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Verification status: pending, verifying, verified, failed, expired"},"verification_token":{"type":["null","string"],"description":"Unique token for domain verification (32-char alphanumeric)"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"},"verified_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when domain was successfully verified (ISO 8601)"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"SSL certificate status: none, pending, issued, failed, expiring, expired"},"ssl_issued_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate was issued (ISO 8601)"},"ssl_expires_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate expires (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","domain","domain_type","status","verification_method","ssl_status","settings","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"tags":["Tenant Domains"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$","description":"Update domain (valid hostname format)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Update verification status"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Update verification method"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"Update SSL certificate status"},"ssl_issued_at":{"type":["string","null"],"format":"date-time","description":"Update SSL certificate issued timestamp (ISO 8601)"},"ssl_expires_at":{"type":["string","null"],"format":"date-time","description":"Update SSL certificate expiration timestamp (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Update domain-specific settings (JSONB)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Domain configuration unique identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant this domain belongs to"},"domain":{"type":"string","description":"Custom domain (e.g., api.wishtree.online)"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api (platform API root, environment-specific target resolved by deployment)"},"status":{"type":"string","enum":["pending","verifying","verified","failed","expired"],"description":"Verification status: pending, verifying, verified, failed, expired"},"verification_token":{"type":["null","string"],"description":"Unique token for domain verification (32-char alphanumeric)"},"verification_method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"},"verified_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when domain was successfully verified (ISO 8601)"},"ssl_status":{"type":"string","enum":["none","pending","issued","failed","expiring","expired"],"description":"SSL certificate status: none, pending, issued, failed, expiring, expired"},"ssl_issued_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate was issued (ISO 8601)"},"ssl_expires_at":{"type":["null","string"],"format":"date-time","description":"Timestamp when SSL certificate expires (ISO 8601)"},"settings":{"type":"object","additionalProperties":true,"description":"Additional domain-specific settings (JSONB)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp (ISO 8601)"}},"required":["id","tenantId","domain","domain_type","status","verification_method","ssl_status","settings","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"tags":["Tenant Domains"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Tenant domain deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenant-domains/{id}/verify":{"post":{"tags":["Tenant Domains"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"domainId":{"type":"string","format":"uuid","description":"Domain configuration ID"},"domain":{"type":"string","description":"Domain being verified"},"verified":{"type":"boolean","description":"Whether verification succeeded"},"method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method used"},"details":{"type":"object","properties":{"cnameTarget":{"type":["null","string"],"description":"Actual CNAME target found"},"expectedTarget":{"type":"string","description":"Expected CNAME target"},"txtRecordFound":{"type":["null","boolean"],"description":"Whether TXT record was found"},"httpFileContent":{"type":["null","string"],"description":"HTTP verification file content"}},"required":["expectedTarget"]},"error":{"type":["null","object"],"properties":{"code":{"type":"string","enum":["DNS_LOOKUP_FAILED","CNAME_MISMATCH","TXT_NOT_FOUND","HTTP_NOT_FOUND","TIMEOUT"],"description":"Error code if verification failed"},"message":{"type":"string","description":"Human-readable error message"}}},"verifiedAt":{"type":["null","string"],"format":"date-time","description":"Timestamp when verification completed (ISO 8601)"}},"required":["domainId","domain","verified","method","details"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/tenant-domains/{id}/verification-instructions":{"get":{"summary":"Get domain verification instructions","tags":["Tenant Domains"],"description":"Retrieve the DNS records and steps required to verify a specific tenant domain.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"domain":{"type":"string","description":"Domain to configure"},"domain_type":{"type":"string","enum":["api"],"description":"Type of domain: api"},"method":{"type":"string","enum":["cname","txt","http"],"description":"Verification method"},"instructions":{"type":"object","properties":{"cname":{"type":"object","properties":{"record_type":{"type":"string","description":"DNS record type (CNAME)"},"name":{"type":"string","description":"DNS record name (subdomain)"},"value":{"type":"string","description":"DNS record value (target)"},"ttl":{"type":"number","description":"Recommended TTL in seconds"}}},"txt":{"type":"object","properties":{"record_type":{"type":"string","description":"DNS record type (TXT)"},"name":{"type":"string","description":"DNS record name"},"value":{"type":"string","description":"Verification token"}}},"http":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL to create verification file"},"content":{"type":"string","description":"File content to place at URL"}}}}}},"required":["domain","domain_type","method","instructions"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/external-apis/openrouter/models":{"get":{"summary":"List OpenRouter models","tags":["Admin"],"description":"Returns the current OpenRouter model catalog for text or image tasks so the admin GUI can restrict selection to supported models only.","parameters":[{"schema":{"type":"string","enum":["text","image"],"default":"text"},"in":"query","name":"task","required":false,"description":"Model catalog segment to return. Use text for translation and language tasks, image for image-generation tasks."},{"schema":{"type":"string","minLength":1},"in":"query","name":"search","required":false,"description":"Optional case-insensitive search filter applied to model id, name, and description."},{"schema":{"type":"integer","minimum":1,"maximum":250,"default":200},"in":"query","name":"limit","required":false,"description":"Maximum number of models to return after filtering."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"task":{"type":"string","enum":["text","image"]},"total":{"type":"integer"},"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Canonical OpenRouter model identifier."},"name":{"type":"string","description":"Human-readable model name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"context_length":{"anyOf":[{"type":"integer"},{"type":"null"}]},"prompt_price":{"anyOf":[{"type":"string"},{"type":"null"}]},"completion_price":{"anyOf":[{"type":"string"},{"type":"null"}]},"image_price":{"anyOf":[{"type":"string"},{"type":"null"}]},"request_price":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_free":{"type":"boolean"}},"required":["id","name","description","context_length","prompt_price","completion_price","image_price","request_price","is_free"],"additionalProperties":false}}},"required":["task","total","models"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/tenant-overrides":{"get":{"summary":"Integration control-plane tenant overrides list","tags":["Admin"],"description":"Returns tenant-specific override rules for integration control-plane operations.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"operation_id":{"type":"string","format":"uuid"},"operation_key":{"type":"string"},"operation_name":{"type":"string"},"enabled":{"type":"boolean"},"preferred_provider_order":{"type":"array","items":{"type":"string"}},"quota_ceiling":{"type":"object","additionalProperties":true},"override_config":{"type":"object","additionalProperties":true},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","operation_id","operation_key","operation_name","enabled","preferred_provider_order","quota_ceiling","override_config","updated_at"]}}},"required":["data"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}},"put":{"summary":"Upsert integration control-plane tenant override","tags":["Admin"],"description":"Creates or updates a tenant override for operation enablement, provider ordering, quotas, and config.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"operation_key":{"type":"string"},"enabled":{"type":"boolean"},"preferred_provider_order":{"type":"array","items":{"type":"string"}},"quota_ceiling":{"type":"object","additionalProperties":true},"override_config":{"type":"object","additionalProperties":true},"customer_credentials":{"type":"object","additionalProperties":true}},"required":["tenantId","operation_key","enabled"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"operation_id":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"customer_credentials":{"type":"object","additionalProperties":true},"quota_ceiling":{"type":"object","additionalProperties":true},"preferred_provider_order":{"type":"array","items":{"type":"string"}},"override_config":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","operation_id","enabled","customer_credentials","quota_ceiling","preferred_provider_order","override_config","created_at","updated_at"]}},"required":["data"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/tenant-overrides/{id}":{"delete":{"summary":"Delete integration control-plane tenant override","tags":["Admin"],"description":"Removes a tenant-specific integration override entry by its identifier.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Tenant override deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/operations":{"get":{"summary":"Integration control-plane operations list","tags":["Admin"],"description":"Returns integration operations together with recent request and failure totals.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"operation_key":{"type":"string"},"operation_name":{"type":"string"},"operation_domain":{"type":"string"},"enabled":{"type":"boolean"},"system_scoped":{"type":"boolean"},"request_count_24h":{"type":"number"},"failure_count_24h":{"type":"number"}},"required":["operation_key","operation_name","operation_domain","enabled","system_scoped","request_count_24h","failure_count_24h"]}}},"required":["data"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/operations/{operationKey}":{"get":{"summary":"Integration control-plane operation detail","tags":["Admin"],"description":"Returns a single integration operation with recent metrics and request log history.","parameters":[{"schema":{"type":"string"},"in":"path","name":"operationKey","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"operation":{"type":"object","additionalProperties":true},"metrics":{"type":"array","items":{"type":"object","additionalProperties":true}},"recent_logs":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["operation","metrics","recent_logs"]}},"required":["data"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/overview":{"get":{"summary":"Integration telemetry overview","tags":["Admin"],"description":"Returns the aggregated health, success-rate, and state-event overview for the integration control plane.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_requests_24h":{"type":"number"},"success_requests_24h":{"type":"number"},"failure_requests_24h":{"type":"number"},"success_rate_24h":{"type":"number"},"warning_state_events_24h":{"type":"number"},"error_state_events_24h":{"type":"number"},"health_status":{"type":"object","properties":{"active":{"type":"number"},"degraded":{"type":"number"},"offline":{"type":"number"},"error":{"type":"number"},"unknown":{"type":"number"}},"required":["active","degraded","offline","error","unknown"]}},"required":["total_requests_24h","success_requests_24h","failure_requests_24h","success_rate_24h","warning_state_events_24h","error_state_events_24h","health_status"]}},"required":["data"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/logs":{"get":{"summary":"Integration request telemetry logs","tags":["Admin"],"description":"Returns paginated integration request log records with optional operation, provider, tenant, and date filters.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false},{"schema":{"type":"string"},"in":"query","name":"operation_key","required":false},{"schema":{"type":"string"},"in":"query","name":"provider_key","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"boolean"},"in":"query","name":"success","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"start_date","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"end_date","required":false},{"schema":{"type":"number","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["data","total","limit","offset"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/metrics":{"get":{"summary":"Integration hourly metrics","tags":["Admin"],"description":"Returns hourly integration metrics with filtering by tenant, operation, provider, and date range.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false},{"schema":{"type":"string"},"in":"query","name":"operation_key","required":false},{"schema":{"type":"string"},"in":"query","name":"provider_key","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"start_date","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"end_date","required":false},{"schema":{"type":"number","minimum":1,"maximum":500,"default":200},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["data","total","limit","offset"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/state":{"get":{"summary":"Integration state events","tags":["Admin"],"description":"Returns integration state transition events and alerts with optional severity and time filters.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false},{"schema":{"type":"string"},"in":"query","name":"state_key","required":false},{"schema":{"type":"string","enum":["info","warning","error","critical"]},"in":"query","name":"severity","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"start_date","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"end_date","required":false},{"schema":{"type":"number","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["data","total","limit","offset"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}}},"/api/v1/secure/admin/external-apis/control-plane/diagnostics":{"get":{"summary":"Integration diagnostics snapshot","tags":["Admin"],"description":"Returns recent failures, state alerts, and provider health checks for integration diagnostics.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recent_failures":{"type":"array","items":{"type":"object","additionalProperties":true}},"recent_state_alerts":{"type":"array","items":{"type":"object","additionalProperties":true}},"latest_health_checks":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["recent_failures","recent_state_alerts","latest_health_checks"]}},"required":["data"],"response":{"400":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"401":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"403":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"404":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"422":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false},"500":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","examples":["AUTHENTICATION_ERROR","NOT_FOUND","VALIDATION_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","examples":[400,401,403,404,422,500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}}},"/api/v1/secure/ai/providers/":{"post":{"summary":"Create external API provider","tags":["AI Providers"],"description":"Create a new external API provider connector","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","minLength":1,"maxLength":100},"api_name":{"type":"string","minLength":1,"maxLength":200},"api_base_url":{"type":"string","minLength":1},"config":{"type":"object"},"auth_config":{"type":"object"},"enabled":{"type":"boolean"},"priority":{"type":"integer","minimum":1,"maximum":100},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":"string","enum":["system_sync","app_service","integration","communication"],"default":"app_service"}},"required":["api_key","api_name","api_base_url"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique connector ID"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tenant ID (NULL = system-level)"},"api_key":{"type":"string","description":"Unique API identifier (e.g., openrouter, rest_countries)"},"api_name":{"type":"string","description":"Human-readable API name"},"api_base_url":{"type":"string","description":"Full base URL for API requests (including version if applicable)"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration (JSONB)"},"auth_config":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"description":"Encrypted authentication credentials (JSONB)"},"enabled":{"type":"boolean","description":"Whether connector is enabled"},"priority":{"type":"integer","minimum":1,"maximum":100,"description":"Priority for failover (1 = highest)"},"status":{"type":"string","enum":["active","degraded","offline","error","unknown"],"description":"Health status"},"last_health_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_success":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_error":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"error_details":{"anyOf":[{"type":"object"},{"type":"null"}]},"consecutive_failures":{"type":"integer","minimum":0},"auto_disable_threshold":{"type":"integer","minimum":1,"default":5},"auto_disabled":{"type":"boolean","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"category":{"type":"string","enum":["system_sync","app_service","integration","communication"],"description":"Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","api_key","api_name","api_base_url","enabled","priority","status","category","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"get":{"summary":"List external API providers","tags":["AI Providers"],"description":"List all external API provider connectors with optional filtering","parameters":[{"schema":{"type":"string"},"in":"query","name":"api_key","required":false},{"schema":{"type":"boolean"},"in":"query","name":"enabled","required":false},{"schema":{"type":"string","enum":["active","degraded","offline","error","unknown"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["system_sync","app_service","integration","communication"]},"in":"query","name":"category","required":false,"description":"Filter by connector category"},{"schema":{"type":"string"},"in":"query","name":"tags","required":false,"description":"Comma-separated tags"},{"schema":{"type":"boolean","default":true},"in":"query","name":"include_system","required":false,"description":"Include system-level connectors"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","default":"priority"},"in":"query","name":"sort","required":false,"description":"Sort field (priority, created_at, api_name, status)"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"in":"query","name":"order","required":false,"description":"Sort order"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique connector ID"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tenant ID (NULL = system-level)"},"api_key":{"type":"string","description":"Unique API identifier (e.g., openrouter, rest_countries)"},"api_name":{"type":"string","description":"Human-readable API name"},"api_base_url":{"type":"string","description":"Full base URL for API requests (including version if applicable)"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration (JSONB)"},"auth_config":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"description":"Encrypted authentication credentials (JSONB)"},"enabled":{"type":"boolean","description":"Whether connector is enabled"},"priority":{"type":"integer","minimum":1,"maximum":100,"description":"Priority for failover (1 = highest)"},"status":{"type":"string","enum":["active","degraded","offline","error","unknown"],"description":"Health status"},"last_health_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_success":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_error":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"error_details":{"anyOf":[{"type":"object"},{"type":"null"}]},"consecutive_failures":{"type":"integer","minimum":0},"auto_disable_threshold":{"type":"integer","minimum":1,"default":5},"auto_disabled":{"type":"boolean","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"category":{"type":"string","enum":["system_sync","app_service","integration","communication"],"description":"Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","api_key","api_name","api_base_url","enabled","priority","status","category","created_at","updated_at"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/ai/providers/dashboard":{"get":{"summary":"Get AI provider dashboard metrics","tags":["AI Providers"],"description":"Get aggregated metrics and statistics for all AI providers","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_providers":{"type":"number"},"active_providers":{"type":"number"},"inactive_providers":{"type":"number"},"error_providers":{"type":"number"},"uptime_percentage":{"type":"number"},"avg_latency_ms":{"type":"number"},"cache_hit_rate":{"type":"number"},"recent_activity":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"provider_name":{"type":"string"},"status":{"type":"string"},"timestamp":{"type":"string"},"latency_ms":{"type":"number"}}}},"provider_stats":{"type":"array","items":{"type":"object","properties":{"provider_key":{"type":"string"},"provider_name":{"type":"string"},"status":{"type":"string"},"success_rate":{"type":"number"},"avg_latency_ms":{"type":"number"},"last_success":{"type":["null","string"]},"last_error":{"type":["null","string"]}}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/ai/providers/{id}":{"get":{"summary":"Get external API provider","tags":["AI Providers"],"description":"Get external API provider by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique connector ID"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tenant ID (NULL = system-level)"},"api_key":{"type":"string","description":"Unique API identifier (e.g., openrouter, rest_countries)"},"api_name":{"type":"string","description":"Human-readable API name"},"api_base_url":{"type":"string","description":"Full base URL for API requests (including version if applicable)"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration (JSONB)"},"auth_config":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"description":"Encrypted authentication credentials (JSONB)"},"enabled":{"type":"boolean","description":"Whether connector is enabled"},"priority":{"type":"integer","minimum":1,"maximum":100,"description":"Priority for failover (1 = highest)"},"status":{"type":"string","enum":["active","degraded","offline","error","unknown"],"description":"Health status"},"last_health_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_success":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_error":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"error_details":{"anyOf":[{"type":"object"},{"type":"null"}]},"consecutive_failures":{"type":"integer","minimum":0},"auto_disable_threshold":{"type":"integer","minimum":1,"default":5},"auto_disabled":{"type":"boolean","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"category":{"type":"string","enum":["system_sync","app_service","integration","communication"],"description":"Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","api_key","api_name","api_base_url","enabled","priority","status","category","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update external API provider","tags":["AI Providers"],"description":"Update external API provider configuration","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"api_name":{"type":"string","minLength":1,"maxLength":200},"api_base_url":{"type":"string","minLength":1},"config":{"type":"object"},"auth_config":{"type":"object"},"enabled":{"type":"boolean"},"priority":{"type":"integer","minimum":1,"maximum":100},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":"string","enum":["system_sync","app_service","integration","communication"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique connector ID"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tenant ID (NULL = system-level)"},"api_key":{"type":"string","description":"Unique API identifier (e.g., openrouter, rest_countries)"},"api_name":{"type":"string","description":"Human-readable API name"},"api_base_url":{"type":"string","description":"Full base URL for API requests (including version if applicable)"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration (JSONB)"},"auth_config":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"description":"Encrypted authentication credentials (JSONB)"},"enabled":{"type":"boolean","description":"Whether connector is enabled"},"priority":{"type":"integer","minimum":1,"maximum":100,"description":"Priority for failover (1 = highest)"},"status":{"type":"string","enum":["active","degraded","offline","error","unknown"],"description":"Health status"},"last_health_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_success":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_error":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"error_details":{"anyOf":[{"type":"object"},{"type":"null"}]},"consecutive_failures":{"type":"integer","minimum":0},"auto_disable_threshold":{"type":"integer","minimum":1,"default":5},"auto_disabled":{"type":"boolean","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"category":{"type":"string","enum":["system_sync","app_service","integration","communication"],"description":"Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","api_key","api_name","api_base_url","enabled","priority","status","category","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete external API provider","tags":["AI Providers"],"description":"Delete external API provider connector","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Provider deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/ai/providers/{id}/enable":{"post":{"summary":"Enable external API provider","tags":["AI Providers"],"description":"Enable an external API provider connector","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique connector ID"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tenant ID (NULL = system-level)"},"api_key":{"type":"string","description":"Unique API identifier (e.g., openrouter, rest_countries)"},"api_name":{"type":"string","description":"Human-readable API name"},"api_base_url":{"type":"string","description":"Full base URL for API requests (including version if applicable)"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration (JSONB)"},"auth_config":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"description":"Encrypted authentication credentials (JSONB)"},"enabled":{"type":"boolean","description":"Whether connector is enabled"},"priority":{"type":"integer","minimum":1,"maximum":100,"description":"Priority for failover (1 = highest)"},"status":{"type":"string","enum":["active","degraded","offline","error","unknown"],"description":"Health status"},"last_health_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_success":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_error":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"error_details":{"anyOf":[{"type":"object"},{"type":"null"}]},"consecutive_failures":{"type":"integer","minimum":0},"auto_disable_threshold":{"type":"integer","minimum":1,"default":5},"auto_disabled":{"type":"boolean","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"category":{"type":"string","enum":["system_sync","app_service","integration","communication"],"description":"Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","api_key","api_name","api_base_url","enabled","priority","status","category","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/ai/providers/{id}/disable":{"post":{"summary":"Disable external API provider","tags":["AI Providers"],"description":"Disable an external API provider connector","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique connector ID"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tenant ID (NULL = system-level)"},"api_key":{"type":"string","description":"Unique API identifier (e.g., openrouter, rest_countries)"},"api_name":{"type":"string","description":"Human-readable API name"},"api_base_url":{"type":"string","description":"Full base URL for API requests (including version if applicable)"},"config":{"type":"object","additionalProperties":true,"description":"Provider-specific configuration (JSONB)"},"auth_config":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"description":"Encrypted authentication credentials (JSONB)"},"enabled":{"type":"boolean","description":"Whether connector is enabled"},"priority":{"type":"integer","minimum":1,"maximum":100,"description":"Priority for failover (1 = highest)"},"status":{"type":"string","enum":["active","degraded","offline","error","unknown"],"description":"Health status"},"last_health_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_success":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_error":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"error_details":{"anyOf":[{"type":"object"},{"type":"null"}]},"consecutive_failures":{"type":"integer","minimum":0},"auto_disable_threshold":{"type":"integer","minimum":1,"default":5},"auto_disabled":{"type":"boolean","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"category":{"type":"string","enum":["system_sync","app_service","integration","communication"],"description":"Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","api_key","api_name","api_base_url","enabled","priority","status","category","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/ai/translate/text":{"post":{"summary":"Translate text","tags":["AI Translation"],"description":"Translate text from one language to another with optional HTML preservation","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["text","source_language","target_language"],"properties":{"text":{"type":"string","minLength":1,"maxLength":10000,"pattern":".*\\S.*"},"source_language":{"type":"string","minLength":2,"maxLength":2},"target_language":{"type":"string","minLength":2,"maxLength":2},"preserve_html":{"type":"boolean","default":false}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"translated_text":{"type":"string"},"source_language":{"type":"string"},"target_language":{"type":"string"},"provider_used":{"type":"string"},"model_used":{"anyOf":[{"type":"string"},{"type":"null"}]},"cached":{"type":"boolean"},"char_count":{"type":"number"},"tokens_used":{"anyOf":[{"type":"object","properties":{"input":{"type":"number"},"output":{"type":"number"},"total":{"type":"number"}},"required":["input","output","total"]},{"type":"null"}]}},"required":["translated_text","source_language","target_language","provider_used","cached","char_count"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/ai/translate/i18n":{"post":{"summary":"Translate i18n JSON structure","tags":["AI Translation"],"description":"Translate entity-style i18n JSON with language keys and name/description fields. When target_languages is omitted, all tenant-enabled languages except the source language are used.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["i18n_data"],"properties":{"i18n_data":{"type":"object","description":"Language-keyed translation input. Current backend support is entity-style content with name/description fields, not arbitrary nested resource-file trees.","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}}},"source_language":{"type":"string","minLength":2,"maxLength":2,"description":"Optional source language. Auto-detected from the first populated language when omitted."},"target_languages":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"Optional explicit target language list. When omitted, the service uses all tenant-enabled languages except the source language."}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}}},"languages_translated":{"type":"array","items":{"type":"string"}},"provider_used":{"type":"string"},"cached":{"type":"boolean"}},"required":["translations_i18n","languages_translated","provider_used","cached"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/ai/translate/entity":{"post":{"summary":"Translate entity","tags":["AI Translation"],"description":"Translate a space, resource, tag, or category and update translations_i18n in the database. When target_languages is omitted, the endpoint fills only missing translated content for tenant-enabled additional languages and leaves existing translated fields unchanged. When target_languages is provided, the selected languages are translated and existing target content is overwritten. The base language is never persisted in translations_i18n.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["entity_type","entity_id"],"properties":{"entity_type":{"type":"string","enum":["space","resource","tag","category"],"description":"Entity kind to translate. For your main use case, use space or resource."},"entity_id":{"type":"string","format":"uuid","description":"UUID of the space, resource, tag, or category to translate."},"source_language":{"type":"string","minLength":2,"maxLength":2,"description":"Optional source language override. Defaults to the entity base language, then falls back to detected translation content."},"target_languages":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"Optional explicit target language list. When omitted, the endpoint fills only missing translated fields for tenant-enabled additional languages. When provided, the selected languages are translated and existing target content is overwritten."}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}}},"languages_translated":{"type":"array","items":{"type":"string"}},"provider_used":{"type":"string"}},"required":["entity_id","entity_type","name","translations_i18n","languages_translated","provider_used"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/ai/translate/entity-type":{"post":{"summary":"Translate all entities of a taxonomy type","tags":["AI Translation"],"description":"Translate all categories or tags for the current tenant in language-first batches. When target_languages is omitted, the endpoint fills only missing tenant-language content.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["entity_type"],"properties":{"entity_type":{"type":"string","enum":["space","resource","tag","category"],"description":"Bulk translation supports spaces, resources, categories, and tags."},"entity_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Optional subset of entity ids to translate. When omitted, all tenant entities of the selected type are considered."},"source_language":{"type":"string","minLength":2,"maxLength":2,"description":"Optional source language override. Defaults to each entity base language."},"target_languages":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"Optional explicit target language list. When omitted, the endpoint fills missing tenant languages only."}},"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entity_type":{"type":"string"},"entities_total":{"type":"number"},"entities_translated":{"type":"number"},"languages_translated":{"type":"array","items":{"type":"string"}},"provider_used":{"type":"string"},"batches_processed":{"type":"number"}},"required":["entity_type","entities_total","entities_translated","languages_translated","provider_used","batches_processed"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/":{"get":{"summary":"List jobs","tags":["Jobs"],"description":"Retrieve registered jobs with optional system-job visibility and runtime enrichment when the scheduler is available.","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"showSystemTypes","required":false,"description":"Show system jobs (default: false)"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Unique job identifier"},"displayName":{"type":"string","description":"Human-readable name"},"description":{"type":"string","description":"Job description"},"schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cron expression"},"scheduleDescription":{"type":"string","description":"Human-readable schedule"},"category":{"type":"string","enum":["cleanup","maintenance","messaging","metrics","media","custom"],"description":"Job category"},"isSystem":{"type":"boolean","description":"Whether this is a system job"},"isActive":{"type":"boolean","description":"Whether job is currently active"},"lastRun":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Last execution time"},"nextRun":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Next scheduled run"},"environment":{"type":"string","enum":["pg_boss","pg_cron","both"],"description":"Execution environment"},"retryConfig":{"type":"object","properties":{"limit":{"type":"number"},"delaySeconds":{"type":"number"},"backoff":{"type":"boolean"}},"description":"Retry configuration"},"enabled":{"type":"boolean","description":"Scheduler active-state alias mirrored in status payloads."}},"required":["name","isSystem"],"additionalProperties":true}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/registry":{"get":{"summary":"Get job registry","tags":["Jobs"],"description":"Get job registry with all job definitions and configurations","parameters":[{"schema":{"type":"string","enum":["cleanup","maintenance","messaging","metrics","media","custom"]},"in":"query","name":"category","required":false,"description":"Filter by job category"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"schedule":{"type":"string"},"scheduleDescription":{"type":"string"},"environment":{"type":"string"},"isSystem":{"type":"boolean"},"enabledByDefault":{"type":"boolean"},"retry":{"type":"object","properties":{"limit":{"type":"number"},"delaySeconds":{"type":"number"},"backoff":{"type":"boolean"}}},"sqlFunction":{"type":"string","nullable":true},"timeoutSeconds":{"type":"number"}}}},"summary":{"type":"object","properties":{"total":{"type":"number"},"scheduled":{"type":"number"},"eventDriven":{"type":"number"},"byCategory":{"type":"object"},"byEnvironment":{"type":"object"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/{name}/status":{"get":{"summary":"Get job status","tags":["Jobs"],"description":"Retrieve runtime status, schedule, and execution metrics for a specific job.","parameters":[{"schema":{"type":"string"},"in":"path","name":"name","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"schedule":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastRun":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"nextRun":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"enabled":{"type":"boolean"},"isSystem":{"type":"boolean"},"runCount":{"type":"number"},"successCount":{"type":"number"},"failureCount":{"type":"number"},"avgDurationMs":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/active":{"get":{"summary":"List active jobs","tags":["Jobs"],"description":"Retrieve the jobs that are currently running for the current tenant or an explicitly requested tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"jobId":{"type":"string"},"jobName":{"type":"string"},"tenantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"type":"string"},"correlationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"data":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/{name}/history":{"get":{"summary":"Get job history","tags":["Jobs"],"description":"Retrieve paginated execution history for a specific job with optional status, date, and correlation filters.","parameters":[{"schema":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateFrom","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateTo","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"correlationId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false},{"schema":{"type":"number","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"name","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"job_id":{"type":"string"},"job_name":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"started_at":{"type":"string","format":"date-time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"tenantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"correlation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"data":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/history":{"get":{"summary":"List job history","tags":["Jobs"],"description":"Retrieve paginated execution history across jobs with optional job, status, date, and correlation filters.","parameters":[{"schema":{"type":"string"},"in":"query","name":"jobName","required":false},{"schema":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateFrom","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateTo","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"correlationId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false},{"schema":{"type":"number","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"job_id":{"type":"string"},"job_name":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"started_at":{"type":"string","format":"date-time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}]},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"tenantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"correlation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"data":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/{name}/trigger":{"post":{"tags":["Jobs"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"tenantId":{"type":"string","format":"uuid"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"name","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jobId":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/{name}/{jobId}":{"delete":{"tags":["Jobs"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"name","required":true},{"schema":{"type":"string"},"in":"path","name":"jobId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cancelled":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/{name}":{"patch":{"tags":["Jobs"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"name","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/jobs/notifications/settings":{"get":{"summary":"List job notification settings","tags":["Jobs"],"description":"Retrieve notification settings for all jobs in the current tenant or for a specific job.","parameters":[{"schema":{"type":"string"},"in":"query","name":"jobName","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"jobName":{"type":"string"},"enabled":{"type":"boolean"},"emailRecipients":{"type":"array","items":{"type":"string","format":"email"}},"notifyOnSuccess":{"type":"boolean"},"notifyOnFailure":{"type":"boolean"}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"tags":["Jobs"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jobName"],"properties":{"jobName":{"type":"string"},"enabled":{"type":"boolean"},"notify_on_failure":{"type":"boolean"},"notify_on_completion":{"type":"boolean"},"notify_on_long_running":{"type":"boolean"},"long_running_threshold_ms":{"type":"number"}}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jobName":{"type":"string"},"enabled":{"type":"boolean"},"emailRecipients":{"type":"array","items":{"type":"string","format":"email"}},"notifyOnSuccess":{"type":"boolean"},"notifyOnFailure":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/webhooks/inbound/sendgrid":{"post":{"summary":"Handle SendGrid webhook","tags":["Webhooks"],"description":"Handle SendGrid webhook events (delivered, bounced, opened, clicked)","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","description":"Event type: delivered, bounce, open, click, etc."},"email":{"type":"string","format":"email","description":"Recipient email address"},"timestamp":{"type":"number","description":"Unix timestamp of the event"},"sg_message_id":{"type":"string","description":"SendGrid message ID"},"reason":{"type":"string","description":"Reason for bounce/drop (if applicable)"},"url":{"type":"string","description":"Clicked URL (for click events)"}},"required":["event","email","timestamp"],"additionalProperties":true},"minItems":1}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/webhooks/inbound/twilio":{"post":{"summary":"Handle Twilio webhook","tags":["Webhooks"],"description":"Handle Twilio status callbacks (SMS, WhatsApp delivery status)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"MessageSid":{"type":"string","description":"Twilio message SID"},"MessageStatus":{"type":"string","description":"Message status: queued, sent, delivered, failed, undelivered"},"ErrorCode":{"type":"string","description":"Twilio error code (if failed)"},"ErrorMessage":{"type":"string","description":"Error message (if failed)"}},"required":["MessageSid","MessageStatus"],"additionalProperties":true}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/webhooks/subscriptions":{"get":{"summary":"List webhook subscriptions","tags":["Webhooks"],"description":"List all webhook subscriptions for the tenant","parameters":[{"schema":{"type":"number","default":20,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"number","default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"boolean"},"in":"query","name":"enabled","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"headers":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","url","events","enabled","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["total","limit","offset"]}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create webhook subscription","tags":["Webhooks"],"description":"Create a new webhook subscription","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","url","events"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Event types to subscribe to"},"enabled":{"type":"boolean","default":true},"secret":{"type":"string","description":"HMAC signing secret (will be generated if not provided)"},"headers":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}],"description":"Custom headers to include in webhook requests"}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"headers":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","url","events","enabled","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/webhooks/event-types":{"get":{"summary":"List webhook event types","tags":["Webhooks"],"description":"List available webhook event types","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"description":{"type":"string"}},"required":["key","value","description"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/webhooks/subscriptions/{id}":{"get":{"summary":"Get webhook subscription","tags":["Webhooks"],"description":"Get a specific webhook subscription","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"headers":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","url","events","enabled","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update webhook subscription","tags":["Webhooks"],"description":"Update a webhook subscription","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"minItems":1},"enabled":{"type":"boolean"},"secret":{"type":"string"},"headers":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"headers":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","name","url","events","enabled","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete webhook subscription","tags":["Webhooks"],"description":"Delete a webhook subscription","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Successfully deleted"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/webhooks/subscriptions/{id}/test":{"post":{"summary":"Test webhook subscription","tags":["Webhooks"],"description":"Send a test webhook to verify the subscription endpoint","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"statusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"responseBody":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"attempts":{"type":"number"},"deliveryTime":{"type":"number"}},"required":["success","attempts","deliveryTime"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/webhooks/subscriptions/{id}/logs":{"get":{"summary":"Get webhook delivery logs","tags":["Webhooks"],"description":"Get delivery logs for a webhook subscription","parameters":[{"schema":{"type":"number","default":50,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subscription_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"event":{"type":"string"},"url":{"type":"string"},"status":{"type":"string","enum":["success","failed"]},"status_code":{"anyOf":[{"type":"number"},{"type":"null"}]},"response_body":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"attempts":{"type":"number"},"delivery_time_ms":{"type":"number"},"created_at":{"type":"string","format":"date-time"}},"required":["id","event","url","status","attempts","delivery_time_ms","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/webhooks/subscriptions/{id}/stats":{"get":{"summary":"Get webhook delivery statistics","tags":["Webhooks"],"description":"Get delivery statistics for a webhook subscription (last 30 days)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"number"},"success":{"type":"number"},"failed":{"type":"number"},"successRate":{"type":"number"},"avgDeliveryTime":{"type":"number"}},"required":["total","success","failed","successRate","avgDeliveryTime"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/audit-logs/":{"get":{"summary":"List audit logs","tags":["Audit Logs"],"description":"Retrieve paginated audit log entries with optional filtering by actor, action, resource, and time range.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"userId","required":false},{"schema":{"type":"string"},"in":"query","name":"action","required":false},{"schema":{"type":"string"},"in":"query","name":"resourceType","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"resourceId","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startDate","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endDate","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"action":{"type":"string"},"resource_type":{"type":"string"},"resource_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"details":{"type":"object","additionalProperties":true,"nullable":true},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}]},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","action","resource_type","created_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/security/config":{"get":{"summary":"Get global security configuration","tags":["Admin"],"description":"Returns platform-wide security settings (DOS, rate limiting, cache, circuit breaker). System admin only.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"dos_enabled":{"type":"boolean"},"dos_max_requests_per_ip":{"type":"number"},"dos_time_window_seconds":{"type":"number"},"dos_block_duration_seconds":{"type":"number"},"queue_enabled":{"type":"boolean"},"queue_max_size":{"type":"number"},"queue_timeout_ms":{"type":"number"},"ip_blacklist_enabled":{"type":"boolean"},"ip_blacklist_auto_block":{"type":"boolean"},"ip_blacklist_auto_block_threshold":{"type":"number"},"ip_blacklist_auto_block_duration_seconds":{"type":"number"},"circuit_breaker_enabled":{"type":"boolean"},"circuit_breaker_cpu_threshold":{"type":"number"},"circuit_breaker_duration_seconds":{"type":"number"},"circuit_breaker_check_interval_seconds":{"type":"number"},"cache_enabled":{"type":"boolean"},"cache_max_entries":{"type":"number"},"cache_default_ttl_seconds":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"updated_by":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update global security configuration","tags":["Admin"],"description":"Update platform-wide security settings. System admin only.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dos_enabled":{"type":"boolean"},"dos_max_requests_per_ip":{"type":"number","minimum":100,"maximum":100000},"dos_time_window_seconds":{"type":"number","minimum":60,"maximum":3600},"dos_block_duration_seconds":{"type":"number","minimum":60,"maximum":86400},"queue_enabled":{"type":"boolean"},"queue_max_size":{"type":"number","minimum":100,"maximum":50000},"queue_timeout_ms":{"type":"number","minimum":1000,"maximum":120000},"ip_blacklist_enabled":{"type":"boolean"},"ip_blacklist_auto_block":{"type":"boolean"},"ip_blacklist_auto_block_threshold":{"type":"number","minimum":3,"maximum":100},"ip_blacklist_auto_block_duration_seconds":{"type":"number","minimum":300,"maximum":604800},"circuit_breaker_enabled":{"type":"boolean"},"circuit_breaker_cpu_threshold":{"type":"number","minimum":50,"maximum":99},"circuit_breaker_duration_seconds":{"type":"number","minimum":60,"maximum":3600},"circuit_breaker_check_interval_seconds":{"type":"number","minimum":5,"maximum":60},"cache_enabled":{"type":"boolean"},"cache_max_entries":{"type":"number","minimum":100,"maximum":100000},"cache_default_ttl_seconds":{"type":"number","minimum":60,"maximum":3600}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"dos_enabled":{"type":"boolean"},"dos_max_requests_per_ip":{"type":"number"},"dos_time_window_seconds":{"type":"number"},"dos_block_duration_seconds":{"type":"number"},"queue_enabled":{"type":"boolean"},"queue_max_size":{"type":"number"},"queue_timeout_ms":{"type":"number"},"ip_blacklist_enabled":{"type":"boolean"},"ip_blacklist_auto_block":{"type":"boolean"},"ip_blacklist_auto_block_threshold":{"type":"number"},"ip_blacklist_auto_block_duration_seconds":{"type":"number"},"circuit_breaker_enabled":{"type":"boolean"},"circuit_breaker_cpu_threshold":{"type":"number"},"circuit_breaker_duration_seconds":{"type":"number"},"circuit_breaker_check_interval_seconds":{"type":"number"},"cache_enabled":{"type":"boolean"},"cache_max_entries":{"type":"number"},"cache_default_ttl_seconds":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"updated_by":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/security/ip-blacklist":{"get":{"summary":"List IP blacklist entries","tags":["Admin"],"description":"Returns all blocked IP addresses. System admin only.","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"active_only","required":false,"description":"Filter to active (non-expired) blocks only"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ip_address":{"type":"string"},"reason":{"type":"string","nullable":true},"blocked_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true},"auto_blocked":{"type":"boolean"},"failed_attempts":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}},"total":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Block an IP address","tags":["Admin"],"description":"Add an IP address to the blacklist. System admin only.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ip_address"],"properties":{"ip_address":{"type":"string","description":"IPv4 or IPv6 address"},"reason":{"type":"string","maxLength":255,"description":"Reason for blocking"},"expires_at":{"type":"string","format":"date-time","description":"Expiration time (null = permanent)"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ip_address":{"type":"string"},"reason":{"type":"string","nullable":true},"blocked_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true},"auto_blocked":{"type":"boolean"},"failed_attempts":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/security/ip-blacklist/{id}":{"get":{"summary":"Get IP blacklist entry","tags":["Admin"],"description":"Get details of a specific blocked IP. System admin only.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ip_address":{"type":"string"},"reason":{"type":"string","nullable":true},"blocked_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true},"auto_blocked":{"type":"boolean"},"failed_attempts":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update IP blacklist entry","tags":["Admin"],"description":"Update reason or expiration of a blocked IP. System admin only.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":255},"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ip_address":{"type":"string"},"reason":{"type":"string","nullable":true},"blocked_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true},"auto_blocked":{"type":"boolean"},"failed_attempts":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Unblock an IP address","tags":["Admin"],"description":"Remove an IP address from the blacklist. System admin only.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"No content"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/security/events":{"get":{"summary":"List security events","tags":["Admin"],"description":"Returns security audit log entries. System admin only.","parameters":[{"schema":{"type":"string"},"in":"query","name":"event_type","required":false,"description":"Filter by event type"},{"schema":{"type":"string","enum":["low","medium","high","critical"]},"in":"query","name":"severity","required":false},{"schema":{"type":"string"},"in":"query","name":"ip_address","required":false,"description":"Filter by IP address"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"since","required":false,"description":"Events since timestamp"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"ip_address":{"type":"string","nullable":true},"user_id":{"type":"string","format":"uuid","nullable":true},"tenantId":{"type":"string","format":"uuid","nullable":true},"details":{"type":"object","additionalProperties":true},"severity":{"type":"string","enum":["low","medium","high","critical"]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"total":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/security/metrics":{"get":{"summary":"Get security metrics","tags":["Admin"],"description":"Returns aggregated security metrics (blocked IPs, events, etc.). System admin only.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_blocked_ips":{"type":"number"},"active_blocked_ips":{"type":"number"},"permanent_blocks":{"type":"number"},"temporary_blocks":{"type":"number"},"auto_blocked_count":{"type":"number"},"events_last_24h":{"type":"number"},"events_by_type":{"type":"object","additionalProperties":{"type":"number"}},"events_by_severity":{"type":"object","additionalProperties":{"type":"number"}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/":{"get":{"summary":"Query historical logs","tags":["Admin"],"description":"System admin only. Query and filter application logs with pagination.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"userId","required":false},{"schema":{"type":"string"},"in":"query","name":"service","required":false},{"schema":{"type":"string","enum":["trace","debug","info","warn","error","fatal"]},"in":"query","name":"level","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startTime","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endTime","required":false},{"schema":{"type":"string"},"in":"query","name":"requestId","required":false},{"schema":{"type":"string"},"in":"query","name":"keyword","required":false},{"schema":{"type":"number","minimum":1,"maximum":1000,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"level":{"type":"string","enum":["trace","debug","info","warn","error","fatal"]},"message":{"type":"string"},"service":{"type":"string"},"tenantId":{"type":"string","format":"uuid","nullable":true},"userId":{"type":"string","format":"uuid","nullable":true},"requestId":{"type":"string","nullable":true},"context":{"type":"object","additionalProperties":true}},"required":["id","timestamp","level","message"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/analytics":{"get":{"summary":"Get log analytics","tags":["Admin"],"description":"System admin only. Get error rates, charts, and performance metrics.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startTime","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endTime","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"errorRate":{"type":"number"},"errorCount":{"type":"number"},"totalRequests":{"type":"number"},"responseTime":{"type":"object","properties":{"p50":{"type":"number"},"p95":{"type":"number"},"p99":{"type":"number"}},"additionalProperties":false},"topErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"count":{"type":"number"},"lastOccurrence":{"type":"string","format":"date-time"}},"additionalProperties":false}},"tenantActivity":{"type":"array","items":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"requestCount":{"type":"number"},"errorCount":{"type":"number"}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/security-audit":{"get":{"summary":"Get security audit log","tags":["Admin"],"description":"System admin only. Get security-related events (failed logins, permission denials, etc.).","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startTime","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endTime","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"userId","required":false},{"schema":{"type":"number","minimum":1,"maximum":1000,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"eventType":{"type":"string","enum":["login_failed","permission_denied","api_key_used","admin_action"]},"userId":{"type":"string","format":"uuid","nullable":true},"tenantId":{"type":"string","format":"uuid","nullable":true},"details":{"type":"object","additionalProperties":true}},"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/config":{"get":{"summary":"Get log configuration","tags":["Admin"],"description":"System admin only. Get current log level configuration, formatting, and cleanup settings.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"logLevels":{"type":"object","description":"Per-service log levels","additionalProperties":{"type":"string","enum":["trace","debug","info","warn","error","fatal"]}},"console":{"type":"object","properties":{"enabled":{"type":"boolean"},"format":{"type":"string","enum":["json","pretty","compact"]},"colorize":{"type":"boolean"},"timestamp":{"type":"boolean"}},"additionalProperties":false},"database":{"type":"object","properties":{"enabled":{"type":"boolean"},"table":{"type":"string"},"batchSize":{"type":"number"},"flushInterval":{"type":"number"}},"additionalProperties":false},"formatting":{"type":"object","properties":{"format":{"type":"string","enum":["json","pretty","compact"]},"includeTimestamp":{"type":"boolean"},"includeService":{"type":"boolean"},"includeContext":{"type":"boolean"},"redactSensitive":{"type":"boolean"}},"additionalProperties":false},"cleanup":{"type":"object","properties":{"enabled":{"type":"boolean"},"retentionDays":{"type":"number","enum":[30,60,90]},"archiveEnabled":{"type":"boolean"},"archiveLocation":{"type":"string"},"cleanupSchedule":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update log configuration","tags":["Admin"],"description":"System admin only. Update log levels, formatting, and cleanup settings. Changes apply without restart.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"logLevels":{"type":"object","additionalProperties":{"type":"string","enum":["trace","debug","info","warn","error","fatal"]}},"console":{"type":"object","properties":{"enabled":{"type":"boolean"},"format":{"type":"string","enum":["json","pretty","compact"]},"colorize":{"type":"boolean"},"timestamp":{"type":"boolean"},"levels":{"type":"array","items":{"type":"string","enum":["trace","debug","info","warn","error","fatal"]}}}},"database":{"type":"object","properties":{"enabled":{"type":"boolean"},"table":{"type":"string"},"batchSize":{"type":"number","minimum":1,"maximum":1000},"flushInterval":{"type":"number","minimum":1000,"maximum":60000},"levels":{"type":"array","items":{"type":"string","enum":["trace","debug","info","warn","error","fatal"]}}}},"formatting":{"type":"object","properties":{"format":{"type":"string","enum":["json","pretty","compact"]},"includeTimestamp":{"type":"boolean"},"includeService":{"type":"boolean"},"includeContext":{"type":"boolean"},"redactSensitive":{"type":"boolean"}}},"cleanup":{"type":"object","properties":{"enabled":{"type":"boolean"},"retentionDays":{"type":"number","enum":[30,60,90]},"archiveEnabled":{"type":"boolean"},"archiveLocation":{"type":"string"},"cleanupSchedule":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"applied":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/config/{section}":{"get":{"summary":"Get section configuration","tags":["Admin"],"description":"System admin only. Get configuration for a specific section.","parameters":[{"schema":{"type":"string","enum":["console","database","formatting","cleanup","log-levels"]},"in":"path","name":"section","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update section configuration","tags":["Admin"],"description":"System admin only. Update configuration for a specific section. Changes apply without restart.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"parameters":[{"schema":{"type":"string","enum":["console","database","formatting","cleanup","log-levels"]},"in":"path","name":"section","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"applied":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/config/validate":{"post":{"summary":"Validate log configuration","tags":["Admin"],"description":"System admin only. Validate configuration before saving. Returns errors and warnings.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"section":{"type":"string","enum":["console","database","formatting","cleanup","log-levels"]},"config":{"type":"object","additionalProperties":true}},"required":["config"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/config/preview":{"post":{"summary":"Preview configuration changes","tags":["Admin"],"description":"System admin only. Preview affected services and impact of configuration changes (AC15 requirement).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"logLevels":{"type":"object","additionalProperties":{"type":"string","enum":["trace","debug","info","warn","error","fatal"]}},"cleanup":{"type":"object","properties":{"retentionDays":{"type":"number","enum":[30,60,90]}}}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affectedServices":{"type":"array","items":{"type":"string"}},"estimatedLogVolume":{"type":"number"},"storageImpact":{"type":"object","properties":{"current":{"type":"number"},"projected":{"type":"number"},"change":{"type":"number"}},"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/export":{"post":{"summary":"Export logs to storage","tags":["Admin"],"description":"System admin only. Export logs to system storage for archiving or analysis.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"tenantId":{"type":"string","format":"uuid"},"level":{"type":"string","enum":["trace","debug","info","warn","error","fatal"]},"format":{"type":"string","enum":["json","csv"],"default":"json"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"},"recordCount":{"type":"number"},"sizeBytes":{"type":"number"}},"required":["message","path","recordCount","sizeBytes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/exports":{"get":{"summary":"List log exports","tags":["Admin"],"description":"System admin only. List available log export files in storage.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"size":{"type":"number"},"createdAt":{"type":"string"}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/exports/{filename}":{"delete":{"summary":"Delete log export","tags":["Admin"],"description":"System admin only. Delete a log export file from storage.","parameters":[{"schema":{"type":"string"},"in":"path","name":"filename","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"deleted":{"type":"boolean"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/logs/config/reset":{"post":{"summary":"Reset log configuration to defaults","tags":["Admin"],"description":"System admin only. Reset all log settings to default values.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"reset":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/system/domains/azure-setup":{"get":{"summary":"Get Azure whitelabel domain manual setup diagnostics","tags":["Domains"],"description":"System admin only. Returns PVE domain status, DNS checks, and manual Azure Container Apps custom-domain setup commands.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$"},"in":"query","name":"domain","required":false,"description":"Optional custom API domain to inspect"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false,"description":"Optional tenant ID filter for system administrators"},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeDns","required":false,"description":"Whether to resolve live DNS records for the returned domains"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"environment":{"type":"string","enum":["development","integration","production"],"description":"Backend application environment"},"platformApiHost":{"type":"string","description":"Canonical platform API hostname for tenant CNAMEs"},"azure":{"type":"object","properties":{"subscriptionId":{"type":"string","description":"Azure subscription ID or placeholder"},"resourceGroup":{"type":"string","description":"Azure resource group for backend Container App"},"containerAppName":{"type":"string","description":"Azure Container App name for this environment"},"defaultHostnameCommand":{"type":"string","description":"Command to read the Container App generated hostname"},"verificationIdCommand":{"type":"string","description":"Command to read the Container App custom-domain verification ID"},"listBindingsCommand":{"type":"string","description":"Command to list existing Container App custom domain bindings"},"portalUrl":{"type":"string","description":"Azure Portal URL for the Container App custom domains blade"}},"required":["subscriptionId","resourceGroup","containerAppName","defaultHostnameCommand","verificationIdCommand","listBindingsCommand","portalUrl"],"additionalProperties":false},"domains":{"type":"array","items":{"type":"object","properties":{"domainId":{"type":["null","string"],"format":"uuid","description":"Tenant domain row ID when configured in PVE"},"tenantId":{"type":["null","string"],"format":"uuid","description":"Owning tenant ID when configured in PVE"},"tenantName":{"type":["null","string"],"description":"Owning tenant display name when known"},"domain":{"type":"string","description":"Custom API domain"},"pveStatus":{"type":"string","enum":["pending","verifying","verified","failed","expired","not_configured"],"description":"PVE tenant-domain verification state"},"sslStatus":{"type":"string","enum":["none","pending","issued","failed","expiring","expired","unknown"],"description":"Stored PVE SSL/certificate state"},"expectedCnameTarget":{"type":"string","description":"PVE expected API CNAME target for this environment"},"cnameTarget":{"type":["null","string"],"description":"Live CNAME target returned by DNS lookup"},"cnameMatchesExpected":{"type":["null","boolean"],"description":"Whether live CNAME matches the PVE expected target"},"asuidHost":{"type":"string","description":"Azure domain verification TXT record host"},"asuidTxtRecords":{"type":"array","items":{"type":"string"},"description":"Live asuid TXT record values returned by DNS lookup"},"commands":{"type":"object","properties":{"addHostname":{"type":"string","description":"Azure CLI command to add the custom hostname"},"bindCertificate":{"type":"string","description":"Azure CLI command to bind an environment-managed certificate"},"showBinding":{"type":"string","description":"Azure CLI command to inspect this hostname binding"},"tlsProbe":{"type":"string","description":"Command to validate HTTPS/TLS for this hostname"},"corsProbe":{"type":"string","description":"Command to validate CORS preflight through this hostname"}},"required":["addHostname","bindCertificate","showBinding","tlsProbe","corsProbe"],"additionalProperties":false},"checks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Stable check identifier"},"label":{"type":"string","description":"Human-readable check label"},"status":{"type":"string","enum":["pass","warning","fail","manual","unknown"],"description":"Current check state"},"detail":{"type":"string","description":"Diagnostic detail and recommended action"}},"required":["key","label","status","detail"],"additionalProperties":false},"description":"Ordered setup/checklist states for this domain"}},"required":["domainId","tenantId","tenantName","domain","pveStatus","sslStatus","expectedCnameTarget","cnameTarget","cnameMatchesExpected","asuidHost","asuidTxtRecords","commands","checks"],"additionalProperties":false},"description":"Configured or requested custom domains with diagnostics"},"manualSteps":{"type":"array","items":{"type":"string"},"description":"Provider-side manual setup steps"},"validationCommands":{"type":"array","items":{"type":"string"},"description":"Commands to validate DNS, Azure binding, TLS, and CORS after setup"}},"required":["environment","platformApiHost","azure","domains","manualSteps","validationCommands"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/default-tenant-storage/status":{"get":{"summary":"Get default tenant storage status","tags":["Storage"],"description":"Get tenant default storage status (quota, usage, available)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"quota_bytes":{"type":"number"},"usage_bytes":{"type":"number"},"available_bytes":{"type":"number"},"usage_percent":{"type":"number"}},"required":["tenantId","enabled","quota_bytes","usage_bytes","available_bytes","usage_percent"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/default-tenant-storage/stats":{"get":{"summary":"Get default tenant storage stats","tags":["Admin"],"description":"Get default tenant storage statistics (system admin only)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_tenants":{"type":"number"},"enabled_tenants":{"type":"number"},"total_quota_bytes":{"type":"number"},"total_usage_bytes":{"type":"number"},"average_usage_percent":{"type":"number"}},"required":["total_tenants","enabled_tenants","total_quota_bytes","total_usage_bytes","average_usage_percent"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/targets":{"get":{"summary":"List storage targets","tags":["Storage"],"description":"List readable storage targets accessible to the current user","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"ownerScope":{"type":"string","enum":["system","tenant"]},"provider":{"type":"string","enum":["supabase","s3","azure"]},"name":{"type":"string"},"enabled":{"type":"boolean"},"readEnabled":{"type":"boolean"},"writeEnabled":{"type":"boolean"},"priority":{"type":"number"},"weight":{"type":"number"},"quotaBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"currentUsageBytes":{"type":"number"},"maxFileSizeBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"healthStatus":{"type":"string","enum":["online","degraded","offline","unknown"]},"lastHealthCheckAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"type":"object","additionalProperties":true},"credentialVersion":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"updatedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","ownerScope","provider","name","enabled","readEnabled","writeEnabled","priority","weight","currentUsageBytes","healthStatus","config","credentialVersion","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create storage target","tags":["Storage"],"description":"Create a canonical storage target","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["provider","name","ownerScope"],"properties":{"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"ownerScope":{"type":"string","enum":["system","tenant"]},"provider":{"type":"string","enum":["supabase","s3","azure"]},"name":{"type":"string","minLength":1,"maxLength":255},"enabled":{"type":"boolean","default":true},"readEnabled":{"type":"boolean","default":true},"writeEnabled":{"type":"boolean","default":true},"priority":{"type":"number","minimum":0,"maximum":1000,"default":100},"weight":{"type":"number","minimum":1,"default":1},"quotaBytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"maxFileSizeBytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"config":{"type":"object","additionalProperties":true}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"ownerScope":{"type":"string","enum":["system","tenant"]},"provider":{"type":"string","enum":["supabase","s3","azure"]},"name":{"type":"string"},"enabled":{"type":"boolean"},"readEnabled":{"type":"boolean"},"writeEnabled":{"type":"boolean"},"priority":{"type":"number"},"weight":{"type":"number"},"quotaBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"currentUsageBytes":{"type":"number"},"maxFileSizeBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"healthStatus":{"type":"string","enum":["online","degraded","offline","unknown"]},"lastHealthCheckAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"type":"object","additionalProperties":true},"credentialVersion":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"updatedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","ownerScope","provider","name","enabled","readEnabled","writeEnabled","priority","weight","currentUsageBytes","healthStatus","config","credentialVersion","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/targets/{target_id}":{"patch":{"summary":"Update storage target","tags":["Storage"],"description":"Update a canonical storage target","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"enabled":{"type":"boolean"},"readEnabled":{"type":"boolean"},"writeEnabled":{"type":"boolean"},"priority":{"type":"number","minimum":0,"maximum":1000},"weight":{"type":"number","minimum":1},"quotaBytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"maxFileSizeBytes":{"anyOf":[{"type":"number","minimum":1},{"type":"null"}]},"healthStatus":{"type":"string","enum":["online","degraded","offline","unknown"]},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"target_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"ownerScope":{"type":"string","enum":["system","tenant"]},"provider":{"type":"string","enum":["supabase","s3","azure"]},"name":{"type":"string"},"enabled":{"type":"boolean"},"readEnabled":{"type":"boolean"},"writeEnabled":{"type":"boolean"},"priority":{"type":"number"},"weight":{"type":"number"},"quotaBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"currentUsageBytes":{"type":"number"},"maxFileSizeBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"healthStatus":{"type":"string","enum":["online","degraded","offline","unknown"]},"lastHealthCheckAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"type":"object","additionalProperties":true},"credentialVersion":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"updatedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","ownerScope","provider","name","enabled","readEnabled","writeEnabled","priority","weight","currentUsageBytes","healthStatus","config","credentialVersion","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete storage target","tags":["Storage"],"description":"Delete a canonical storage target","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"target_id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/targets/{target_id}/health/refresh":{"post":{"summary":"Refresh storage target health","tags":["Storage"],"description":"Run an explicit health check for a storage target and persist the canonical health state","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"target_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"ownerScope":{"type":"string","enum":["system","tenant"]},"provider":{"type":"string","enum":["supabase","s3","azure"]},"name":{"type":"string"},"enabled":{"type":"boolean"},"readEnabled":{"type":"boolean"},"writeEnabled":{"type":"boolean"},"priority":{"type":"number"},"weight":{"type":"number"},"quotaBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"currentUsageBytes":{"type":"number"},"maxFileSizeBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"healthStatus":{"type":"string","enum":["online","degraded","offline","unknown"]},"lastHealthCheckAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"type":"object","additionalProperties":true},"credentialVersion":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"updatedBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","tenantId","ownerScope","provider","name","enabled","readEnabled","writeEnabled","priority","weight","currentUsageBytes","healthStatus","config","credentialVersion","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/targets/{target_id}/files":{"get":{"summary":"List target files","tags":["Storage"],"description":"List files in a canonical storage target","parameters":[{"schema":{"type":"string","default":""},"in":"query","name":"path","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"target_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"File or folder name"},"id":{"type":["null","string"],"description":"File ID (null for folders)"},"fileId":{"type":["null","string"],"description":"Mapped stable file ID (null for folders or unmapped files)"},"mediaFileId":{"type":["null","string"],"description":"Canonical media file ID for media-specific actions"},"targetId":{"type":["null","string"],"description":"Canonical storage target ID"},"path":{"type":"string","description":"Full path to the file/folder"},"isFolder":{"type":"boolean","description":"True if this is a folder"},"size":{"type":"number","description":"File size in bytes (0 for folders)"},"mimeType":{"type":["null","string"],"description":"MIME type of the file"},"isImage":{"type":"boolean","description":"True if this is an image file"},"thumbnailUrl":{"type":["null","string"],"description":"URL for thumbnail (images only)"},"publicUrl":{"type":["null","string"],"description":"URL for public access/download"},"owner":{"type":["null","string"],"description":"Owner user ID"},"createdBy":{"type":["null","string"],"description":"Created by user ID"},"lastAccessedAt":{"type":["null","string"],"description":"Last access timestamp"},"referenceCount":{"type":"number","description":"Number of linked entity references"},"created_at":{"type":["null","string"],"description":"Creation timestamp"},"updated_at":{"type":["null","string"],"description":"Last update timestamp"},"metadata":{"type":"object","additionalProperties":true,"description":"File metadata from storage"}},"required":["name","path","isFolder","size","isImage","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/targets/{target_id}/thumbnail/{*}":{"get":{"summary":"Get target file thumbnail","tags":["Storage"],"description":"Get thumbnail for an image file from a canonical storage target","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"target_id","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/targets/{target_id}/download/{*}":{"get":{"summary":"Download target file","tags":["Storage"],"description":"Download file from a canonical storage target","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"target_id","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/policies":{"get":{"summary":"List storage policies","tags":["Storage"],"description":"List RLS policies for storage.objects (read-only, informational)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"schemaname":{"type":"string"},"tablename":{"type":"string"},"policyname":{"type":"string"},"permissive":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"cmd":{"type":"string"},"qual":{"type":"string"},"with_check":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/storage/distribution-config":{"get":{"summary":"Get distribution configuration","tags":["Storage"],"description":"Get target-based storage routing configuration and validation metadata for active storage targets","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provider":{"type":"string","enum":["supabase","s3","azure"]},"strategy":{"type":"string"},"enableDistribution":{"type":"boolean"},"fallbackEnabled":{"type":"boolean"},"targetKind":{"type":"string","enum":["bucket","container"]},"thumbnailLocationPolicy":{"type":"string"},"routingModel":{"type":"string","enum":["provider-first-mapping"]},"placementAuthority":{"type":"string","enum":["storage-layer"]},"provider_capabilities":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["supabase","s3","azure"]},"label":{"type":"string"},"description":{"type":"string"},"deliveryMode":{"type":"string","enum":["proxy-only","signed-redirect"]},"supportsFallback":{"type":"boolean"},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"scope":{"type":"string","enum":["config","credentials"]},"input":{"type":"string","enum":["text","password"]},"required":{"type":"boolean"},"helpText":{"type":["null","string"]},"placeholder":{"type":["null","string"]}},"required":["key","label","scope","input","required"],"additionalProperties":false}}},"required":["provider","label","description","deliveryMode","supportsFallback","fields"],"additionalProperties":false}},"defaultTargetId":{"type":["null","string"]},"defaultTarget":{"type":["null","string"]},"targets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scope":{"type":"string","enum":["system","tenant"]},"routingMetadata":{"type":"object","properties":{"placementMode":{"type":"string","enum":["provider-first"]},"placementAuthority":{"type":"string","enum":["storage-layer"]},"thumbnailPlacement":{"type":"string","enum":["same-as-original"]}},"required":["placementMode","placementAuthority","thumbnailPlacement"],"additionalProperties":false},"validationMetadata":{"type":"object","properties":{"allowedMimeTypes":{"type":"array","items":{"type":"string"}}},"required":["allowedMimeTypes"],"additionalProperties":false},"priority":{"type":"number"},"active":{"type":"boolean"}},"required":["id","name","scope","routingMetadata","validationMetadata","priority","active"],"additionalProperties":false}},"thumbnailColocation":{"type":"object","properties":{"mode":{"type":"string","enum":["same-as-original"]},"enforcedBy":{"type":"string","enum":["storage-layer"]}},"required":["mode","enforcedBy"],"additionalProperties":false},"fallbackChain":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update distribution configuration","tags":["Storage"],"description":"Update bucket distribution configuration","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"string","enum":["single-target","sequential","distributed"]},"fallbackChain":{"type":"array","items":{"type":"string","format":"uuid"}},"defaultTargetId":{"type":["string","null"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"provider":{"type":"string","enum":["supabase","s3","azure"]},"defaultTargetId":{"type":["null","string"]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/files/upload":{"post":{"summary":"Upload file","tags":["Files"],"description":"Upload file with intelligent storage distribution","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fileId":{"type":"string","format":"uuid"},"targetId":{"type":"string","format":"uuid"},"providerPath":{"type":"string"},"publicUrl":{"type":"string"},"sizeBytes":{"type":"number"},"originalFilename":{"type":"string"},"contentType":{"type":"string"}},"required":["fileId","targetId","providerPath","publicUrl","sizeBytes"],"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/files/search":{"get":{"summary":"Search files","tags":["Files"],"description":"Search files with filters","parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":false,"description":"Search query (matches filename)"},{"schema":{"type":"string"},"in":"query","name":"contentType","required":false,"description":"Filter by content type (e.g., image, video, application/pdf)"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"spaceId","required":false,"description":"Filter by space ID"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"resourceId","required":false,"description":"Filter by resource ID"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"targetId","required":false,"description":"Filter by canonical storage target ID"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenantId","required":false,"description":"System admin only: filter by tenant ID. Omit to search across all tenants."},{"schema":{"type":"string"},"in":"query","name":"pathPrefix","required":false,"description":"Limit results to files whose provider path starts with this prefix"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"uploadedAfter","required":false,"description":"Filter files uploaded after this date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"uploadedBefore","required":false,"description":"Filter files uploaded before this date"},{"schema":{"type":"string","enum":["uploaded_at","original_filename","size_bytes"],"default":"uploaded_at"},"in":"query","name":"sortBy","required":false,"description":"Sort field"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"in":"query","name":"sortOrder","required":false,"description":"Sort order"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Pagination offset"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"mediaFileId":{"type":"string","format":"uuid","nullable":true},"tenantId":{"type":"string","format":"uuid"},"originalFilename":{"type":"string"},"contentType":{"type":"string","nullable":true},"sizeBytes":{"type":"number"},"spaceId":{"type":"string","format":"uuid","nullable":true},"resourceId":{"type":"string","format":"uuid","nullable":true},"targetId":{"type":"string","format":"uuid","nullable":true},"providerName":{"type":"string"},"providerType":{"type":"string","nullable":true},"providerAccess":{"type":"string","enum":["public","private"],"nullable":true},"providerPath":{"type":"string"},"publicUrl":{"type":"string","nullable":true},"uploadedAt":{"type":"string","format":"date-time"},"lastAccessedAt":{"type":"string","format":"date-time","nullable":true},"movedCount":{"type":"number"},"lastMovedAt":{"type":"string","format":"date-time","nullable":true},"referenceCount":{"type":"number"},"metadata":{"type":"object","additionalProperties":true,"nullable":true}},"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/files/statistics":{"get":{"summary":"Get file statistics","tags":["Files"],"description":"Get file statistics for tenant","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totalFiles":{"type":"number"},"totalSizeBytes":{"type":"number"},"byContentType":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"number"},"sizeBytes":{"type":"number"}},"additionalProperties":false}},"byTarget":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"number"},"sizeBytes":{"type":"number"}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/files/{fileId}/download":{"get":{"summary":"Download file","tags":["Files"],"description":"Download file by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"fileId","required":true,"description":"File ID"}],"responses":{"200":{"description":"File stream","content":{"application/json":{"schema":{"type":"string","format":"binary","description":"File stream"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/files/{fileId}":{"get":{"summary":"Get file metadata","tags":["Files"],"description":"Get file metadata","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"fileId","required":true,"description":"File ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"targetId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"providerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerPath":{"type":"string"},"originalFilename":{"type":"string"},"contentType":{"anyOf":[{"type":"string"},{"type":"null"}]},"sizeBytes":{"type":"number"},"spaceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"resourceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"publicUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"uploadedAt":{"type":"string","format":"date-time"},"lastAccessedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"movedCount":{"type":"number"},"lastMovedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"referenceCount":{"type":"number"},"metadata":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"createdBy":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}},"delete":{"summary":"Delete file","tags":["Files"],"description":"Delete file","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"fileId","required":true,"description":"File ID"}],"responses":{"204":{"description":"File deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/files/{fileId}/move":{"post":{"summary":"Move file","tags":["Files"],"description":"Move file to different storage provider","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["targetId"],"properties":{"targetId":{"type":"string","format":"uuid","description":"Canonical storage target ID"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"fileId","required":true,"description":"File ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/files/migrations/":{"post":{"summary":"Create file migration job","tags":["Files"],"description":"Create a bulk file migration job","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":1000,"description":"Explicit file IDs to migrate"},"sourceTargetId":{"type":"string","format":"uuid","description":"Source storage target ID used to migrate all files currently mapped to that target"},"targetId":{"type":"string","format":"uuid","description":"Canonical destination storage target ID. Omit to use the tenant storage distribution chain."}},"anyOf":[{"required":["fileIds"]},{"required":["sourceTargetId"]}],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"fileIds":{"type":"array","items":{"type":"string","format":"uuid"}},"targetId":{"type":"string","format":"uuid"},"status":{"type":"string"},"progress":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"failed":{"type":"number"},"currentFileId":{"type":"string","nullable":true},"percent":{"type":"number"},"currentTaskLabel":{"type":"string","nullable":true},"destinationMode":{"type":"string","enum":["target","distribution"],"nullable":true}},"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdBy":{"type":"string","format":"uuid"},"error":{"type":"string","nullable":true},"failureDetails":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string"},"error":{"type":"string"}},"additionalProperties":false}},"summary":{"anyOf":[{"type":"object","properties":{"totalTasks":{"type":"number"},"completedTasks":{"type":"number"},"failedTasks":{"type":"number"},"migratedFiles":{"type":"number"},"failedFiles":{"type":"number"},"consistencyChecks":{"type":"array","items":{"type":"object","properties":{"phase":{"type":"string","enum":["preflight","postflight"]},"checkedAt":{"type":"string","format":"date-time"},"totalIssues":{"type":"number"},"repairableIssues":{"type":"number"},"fatalIssues":{"type":"number"},"missingMappings":{"type":"number"},"pathMismatches":{"type":"number"},"versionMismatches":{"type":"number"},"missingVersionHistory":{"type":"number"},"staleBucketMetadata":{"type":"number"},"staleThumbnailMetadata":{"type":"number"},"thumbnailColocationDrift":{"type":"number"}},"additionalProperties":false}}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}},"get":{"summary":"List file migration jobs","tags":["Files"],"description":"List file migration jobs","parameters":[{"schema":{"type":"string","enum":["pending","in_progress","completed","failed","cancelled"]},"in":"query","name":"status","required":false,"description":"Filter by status"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of results"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Pagination offset"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"fileIds":{"type":"array","items":{"type":"string","format":"uuid"}},"targetId":{"type":"string","format":"uuid"},"status":{"type":"string"},"progress":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"failed":{"type":"number"},"currentFileId":{"type":"string","nullable":true},"percent":{"type":"number"},"currentTaskLabel":{"type":"string","nullable":true},"destinationMode":{"type":"string","enum":["target","distribution"],"nullable":true}},"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdBy":{"type":"string","format":"uuid"},"error":{"type":"string","nullable":true},"failureDetails":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string"},"error":{"type":"string"}},"additionalProperties":false}},"summary":{"anyOf":[{"type":"object","properties":{"totalTasks":{"type":"number"},"completedTasks":{"type":"number"},"failedTasks":{"type":"number"},"migratedFiles":{"type":"number"},"failedFiles":{"type":"number"},"consistencyChecks":{"type":"array","items":{"type":"object","properties":{"phase":{"type":"string","enum":["preflight","postflight"]},"checkedAt":{"type":"string","format":"date-time"},"totalIssues":{"type":"number"},"repairableIssues":{"type":"number"},"fatalIssues":{"type":"number"},"missingMappings":{"type":"number"},"pathMismatches":{"type":"number"},"versionMismatches":{"type":"number"},"missingVersionHistory":{"type":"number"},"staleBucketMetadata":{"type":"number"},"staleThumbnailMetadata":{"type":"number"},"thumbnailColocationDrift":{"type":"number"}},"additionalProperties":false}}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}},"total":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/files/migrations/default-tenant-storage":{"post":{"summary":"Create default tenant storage migration job","tags":["Files"],"description":"Create a migration job that moves existing tenant files into the tenant-owned default storage target","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"fileIds":{"type":"array","items":{"type":"string","format":"uuid"}},"targetId":{"type":"string","format":"uuid"},"status":{"type":"string"},"progress":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"failed":{"type":"number"},"currentFileId":{"type":"string","nullable":true},"percent":{"type":"number"},"currentTaskLabel":{"type":"string","nullable":true},"destinationMode":{"type":"string","enum":["target","distribution"],"nullable":true}},"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdBy":{"type":"string","format":"uuid"},"error":{"type":"string","nullable":true},"failureDetails":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string"},"error":{"type":"string"}},"additionalProperties":false}},"summary":{"anyOf":[{"type":"object","properties":{"totalTasks":{"type":"number"},"completedTasks":{"type":"number"},"failedTasks":{"type":"number"},"migratedFiles":{"type":"number"},"failedFiles":{"type":"number"},"consistencyChecks":{"type":"array","items":{"type":"object","properties":{"phase":{"type":"string","enum":["preflight","postflight"]},"checkedAt":{"type":"string","format":"date-time"},"totalIssues":{"type":"number"},"repairableIssues":{"type":"number"},"fatalIssues":{"type":"number"},"missingMappings":{"type":"number"},"pathMismatches":{"type":"number"},"versionMismatches":{"type":"number"},"missingVersionHistory":{"type":"number"},"staleBucketMetadata":{"type":"number"},"staleThumbnailMetadata":{"type":"number"},"thumbnailColocationDrift":{"type":"number"}},"additionalProperties":false}}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/files/migrations/{jobId}":{"get":{"summary":"Get file migration job","tags":["Files"],"description":"Get migration job details","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"jobId","required":true,"description":"Migration job ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"fileIds":{"type":"array","items":{"type":"string","format":"uuid"}},"targetId":{"type":"string","format":"uuid"},"status":{"type":"string"},"progress":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"failed":{"type":"number"},"currentFileId":{"type":"string","nullable":true},"percent":{"type":"number"},"currentTaskLabel":{"type":"string","nullable":true},"destinationMode":{"type":"string","enum":["target","distribution"],"nullable":true}},"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdBy":{"type":"string","format":"uuid"},"error":{"type":"string","nullable":true},"failureDetails":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string"},"error":{"type":"string"}},"additionalProperties":false}},"summary":{"anyOf":[{"type":"object","properties":{"totalTasks":{"type":"number"},"completedTasks":{"type":"number"},"failedTasks":{"type":"number"},"migratedFiles":{"type":"number"},"failedFiles":{"type":"number"},"consistencyChecks":{"type":"array","items":{"type":"object","properties":{"phase":{"type":"string","enum":["preflight","postflight"]},"checkedAt":{"type":"string","format":"date-time"},"totalIssues":{"type":"number"},"repairableIssues":{"type":"number"},"fatalIssues":{"type":"number"},"missingMappings":{"type":"number"},"pathMismatches":{"type":"number"},"versionMismatches":{"type":"number"},"missingVersionHistory":{"type":"number"},"staleBucketMetadata":{"type":"number"},"staleThumbnailMetadata":{"type":"number"},"thumbnailColocationDrift":{"type":"number"}},"additionalProperties":false}}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}},"delete":{"summary":"Cancel file migration job","tags":["Files"],"description":"Cancel a migration job","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"jobId","required":true,"description":"Migration job ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/files/migrations/{jobId}/start":{"post":{"summary":"Start file migration job","tags":["Files"],"description":"Start processing a migration job","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"maxConcurrent":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"Maximum concurrent file migrations"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"jobId","required":true,"description":"Migration job ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"progress":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"failed":{"type":"number"},"currentFileId":{"type":"string","nullable":true},"percent":{"type":"number"},"currentTaskLabel":{"type":"string","nullable":true},"destinationMode":{"type":"string","enum":["target","distribution"],"nullable":true}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/secure/contacts/":{"get":{"summary":"List contacts","tags":["Contacts"],"description":"List contacts with optional filters","parameters":[{"schema":{"type":"string"},"in":"query","name":"email","required":false,"description":"Filter by email (partial match)"},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Filter by name (first_name or last_name partial match)"},{"schema":{"type":"boolean"},"in":"query","name":"hasPhone","required":false,"description":"Filter contacts that have a phone number"},{"schema":{"type":"number","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset","required":false,"description":"Pagination offset"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Create contact","tags":["Contacts"],"description":"Create a new contact","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","maxLength":100,"description":"Passport first name (romanized)"},"middleName":{"type":"string","maxLength":100,"description":"Passport middle name (optional)"},"lastName":{"type":"string","maxLength":100,"description":"Passport last name (romanized)"},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":50},"url":{"type":"string","format":"uri"},"address":{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"notes":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/contacts/{id}":{"get":{"summary":"Get contact","tags":["Contacts"],"description":"Get a contact by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"patch":{"summary":"Update contact","tags":["Contacts"],"description":"Update a contact","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"firstName":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Passport first name (romanized)"},"middleName":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Passport middle name (optional)"},"lastName":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Passport last name (romanized)"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete contact","tags":["Contacts"],"description":"Delete a contact","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"204":{"description":"Contact deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/contacts/{id}/references":{"get":{"summary":"List contact references","tags":["Contacts"],"description":"Get all entities (users, spaces, resources) linked to a contact","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["user","space","resource"]},"entity_id":{"type":"string","format":"uuid"},"entity_name":{"type":"string"},"entity_description":{"type":["null","string"]},"entity_status":{"type":["null","string"]},"is_primary":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","entity_type","entity_id","entity_name","is_primary","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/contacts":{"get":{"summary":"List space contacts","tags":["Spaces"],"description":"Get contacts linked to a space","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["user","space","resource"]},"entity_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"is_primary":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["id","tenantId","entity_type","entity_id","contact_id","is_primary","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Link space contact","tags":["Spaces"],"description":"Link a contact to a space","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["contactId"],"properties":{"contactId":{"type":"string","format":"uuid"},"isPrimary":{"type":"boolean"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["user","space","resource"]},"entity_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"is_primary":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["id","tenantId","entity_type","entity_id","contact_id","is_primary","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/spaces/{id}/contacts/{contactId}":{"delete":{"summary":"Unlink space contact","tags":["Spaces"],"description":"Unlink a contact from a space","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Entity UUID (space or resource)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"contactId","required":true,"description":"Contact UUID to unlink"}],"responses":{"204":{"description":"Contact unlinked from space successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/contacts":{"get":{"summary":"List resource contacts","tags":["Resources"],"description":"Get contacts linked to a resource","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["user","space","resource"]},"entity_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"is_primary":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["id","tenantId","entity_type","entity_id","contact_id","is_primary","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Link resource contact","tags":["Resources"],"description":"Link a contact to a resource","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["contactId"],"properties":{"contactId":{"type":"string","format":"uuid"},"isPrimary":{"type":"boolean"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["user","space","resource"]},"entity_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"is_primary":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["id","tenantId","entity_type","entity_id","contact_id","is_primary","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/resources/{id}/contacts/{contactId}":{"delete":{"summary":"Unlink resource contact","tags":["Resources"],"description":"Unlink a contact from a resource","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Entity UUID (space or resource)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"contactId","required":true,"description":"Contact UUID to unlink"}],"responses":{"204":{"description":"Contact unlinked from resource successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/{id}/contacts":{"get":{"summary":"List user contacts","tags":["Users"],"description":"Get contacts linked to a user","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["user","space","resource"]},"entity_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"is_primary":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["id","tenantId","entity_type","entity_id","contact_id","is_primary","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}},"post":{"summary":"Link user contact","tags":["Users"],"description":"Link a contact to a user","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["contactId"],"properties":{"contactId":{"type":"string","format":"uuid"},"isPrimary":{"type":"boolean"}},"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Contact or entity UUID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["user","space","resource"]},"entity_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"is_primary":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"first_name":{"type":["null","string"],"description":"Passport first name (romanized)"},"middle_name":{"type":["null","string"],"description":"Passport middle name (optional)"},"last_name":{"type":["null","string"],"description":"Passport last name (romanized)"},"email":{"type":["null","string"],"format":"email"},"phone":{"type":["null","string"]},"url":{"type":["null","string"],"format":"uri"},"address":{"anyOf":[{"type":"object","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"notes":{"type":["null","string"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":["null","string"],"format":"uuid"},"updated_by":{"type":["null","string"],"format":"uuid"}},"required":["id","tenantId","created_at","updated_at"],"additionalProperties":false}},"required":["id","tenantId","entity_type","entity_id","contact_id","is_primary","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/{id}/contacts/{contactId}":{"delete":{"summary":"Unlink user contact","tags":["Users"],"description":"Unlink a contact from a user","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Entity UUID (space or resource)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"contactId","required":true,"description":"Contact UUID to unlink"}],"responses":{"204":{"description":"Contact unlinked from user successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/users/export":{"get":{"summary":"Export contacts","tags":["Contacts"],"description":"Export contacts to Excel/CSV/TSV","parameters":[{"schema":{"type":"string","enum":["xlsx","csv","tsv","json","json-schema"],"default":"xlsx"},"in":"query","name":"format","required":false,"description":"Export file format (xlsx, csv, tsv)"},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeExample","required":false,"description":"Include example row if data is empty"},{"schema":{"type":"number","minimum":1,"maximum":10000,"default":10000},"in":"query","name":"limit","required":false,"description":"Maximum number of rows to export"},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Offset for pagination"}],"responses":{"200":{"description":"Binary file download","content":{"application/json":{"schema":{"description":"Binary file download","type":"string","format":"binary"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/users/import":{"post":{"summary":"Import contacts","tags":["Contacts"],"description":"Import contacts from Excel/CSV/TSV file","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether import completed without critical errors"},"dryRun":{"type":"boolean","description":"Whether this was a validation-only dry run"},"entityType":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"],"description":"Entity type that was imported"},"stats":{"type":"object","properties":{"created":{"type":"number","description":"Number of entities created"},"updated":{"type":"number","description":"Number of entities updated"},"skipped":{"type":"number","description":"Number of entities skipped (merge strategy)"},"duplicates":{"type":"number","description":"Number of duplicate entries detected"},"errors":{"type":"number","description":"Number of rows with errors"}},"required":["created","updated","skipped","duplicates","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","description":"Row number (1-based, including header)"},"column":{"type":"string","description":"Column name where error occurred"},"value":{"type":"string","description":"Value that caused the error"},"identifier":{"type":"string","description":"Entity identifier (name, key, id)"},"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["INVALID_FORMAT","REQUIRED_FIELD","INVALID_UUID","DUPLICATE_ENTRY","REFERENCE_NOT_FOUND","VALIDATION_ERROR","IMPORT_ERROR","FILE_ERROR"]}},"required":["identifier","message","code"],"additionalProperties":false},"description":"Detailed error information per row"},"processedRows":{"type":"number","description":"Total number of rows processed"},"totalRows":{"type":"number","description":"Total number of rows in file"}},"required":["success","dryRun","entityType","stats","warnings","errors"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/tenants/{id}/default-tenant-storage":{"patch":{"summary":"Update tenant default storage","tags":["Admin"],"description":"Update tenant default storage configuration (system admin only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Must remain true for default tenant storage"},"quota_bytes":{"type":"number","minimum":1}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"quota_bytes":{"type":"number"},"usage_bytes":{"type":"number"},"available_bytes":{"type":"number"},"usage_percent":{"type":"number"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}},"/api/v1/secure/export/{entityType}":{"get":{"summary":"Export entities to Excel/CSV/TSV","tags":["Export/Import"],"description":"\nExport entities of the specified type to Excel (xlsx), CSV, or TSV format.\n\n**Supported Entity Types:**\n- resources: Resources with categories, tags, and current location\n- spaces: Spaces with categories, tags, and home location\n- categories: Category hierarchy with parent references\n- tags: Tags with display names\n- contacts: Contact information with addresses\n- groups: Groups with permissions\n\n**Features:**\n- Multi-language translation columns for each tenant language\n- Column descriptions as Excel comments\n- Example row if dataset is empty\n- Pagination support for large datasets\n\n**Export Limits:**\n- Maximum 10,000 rows per export\n- Use offset parameter for pagination\n      ","parameters":[{"schema":{"type":"string","enum":["xlsx","csv","tsv","json","json-schema"],"default":"xlsx"},"in":"query","name":"format","required":false,"description":"Export file format (xlsx, csv, tsv)"},{"schema":{"type":"boolean","default":true},"in":"query","name":"includeExample","required":false,"description":"Include example row if data is empty"},{"schema":{"type":"number","minimum":1,"maximum":10000,"default":10000},"in":"query","name":"limit","required":false,"description":"Maximum number of rows to export"},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Offset for pagination"},{"schema":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"]},"in":"path","name":"entityType","required":true,"description":"Entity type to export"}],"responses":{"200":{"description":"Binary file download (xlsx, csv, or tsv)","content":{"application/json":{"schema":{"description":"Binary file download (xlsx, csv, or tsv)","type":"string","format":"binary"}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/export/":{"get":{"summary":"List available export types","tags":["Export/Import"],"description":"Returns a list of entity types that can be exported.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entityTypes":{"type":"array","items":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"]}},"formats":{"type":"array","items":{"type":"string","enum":["xlsx","csv","tsv"]}}}}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/import/{entityType}":{"post":{"summary":"Import entities from Excel/CSV/TSV file","tags":["Export/Import"],"description":"\nImport entities of the specified type from an Excel (xlsx/xls), CSV, or TSV file.\n\n**Supported Entity Types:**\n- resources: Resources with categories, tags, and location\n- spaces: Spaces with categories, tags, and home location\n- categories: Category hierarchy with parent references\n- tags: Tags with display names\n- contacts: Contact information with addresses\n- groups: Groups with permissions\n\n**Import Options (multipart form field: options):**\n- dryRun: Validate without saving (default: false)\n- mergeStrategy: skip | replace | merge (default: skip)\n- defaultTypeDefinitionId: Default type for new entities\n- defaultCategoryId: Default category for new entities\n- skipErrors: Continue on row errors (default: true)\n- createMissingTags: Create tags that don't exist (default: false)\n\n**File Requirements:**\n- Maximum file size: 10MB\n- Maximum rows: 10,000\n- Header row required\n- Supported formats: xlsx, xls, csv, tsv\n\n**Column Handling:**\n- Empty 'id' column: Create new entity\n- Valid UUID in 'id': Update existing entity\n- Translation columns: name_de, description_fr, etc.\n- Categories: Comma-separated keys or names\n- Tags: Comma-separated names\n      ","parameters":[{"schema":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"]},"in":"path","name":"entityType","required":true,"description":"Entity type to import"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether import completed without critical errors"},"dryRun":{"type":"boolean","description":"Whether this was a validation-only dry run"},"entityType":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"],"description":"Entity type that was imported"},"stats":{"type":"object","properties":{"created":{"type":"number","description":"Number of entities created"},"updated":{"type":"number","description":"Number of entities updated"},"skipped":{"type":"number","description":"Number of entities skipped (merge strategy)"},"duplicates":{"type":"number","description":"Number of duplicate entries detected"},"errors":{"type":"number","description":"Number of rows with errors"}},"required":["created","updated","skipped","duplicates","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","description":"Row number (1-based, including header)"},"column":{"type":"string","description":"Column name where error occurred"},"value":{"type":"string","description":"Value that caused the error"},"identifier":{"type":"string","description":"Entity identifier (name, key, id)"},"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["INVALID_FORMAT","REQUIRED_FIELD","INVALID_UUID","DUPLICATE_ENTRY","REFERENCE_NOT_FOUND","VALIDATION_ERROR","IMPORT_ERROR","FILE_ERROR"]}},"required":["identifier","message","code"],"additionalProperties":false},"description":"Detailed error information per row"},"processedRows":{"type":"number","description":"Total number of rows processed"},"totalRows":{"type":"number","description":"Total number of rows in file"}},"required":["success","dryRun","entityType","stats","warnings","errors"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/import/":{"get":{"summary":"List available import types and options","tags":["Export/Import"],"description":"Returns a list of entity types that can be imported and available options.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entityTypes":{"type":"array","items":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"]}},"formats":{"type":"array","items":{"type":"string","enum":["xlsx","xls","csv","tsv"]}},"mergeStrategies":{"type":"array","items":{"type":"string","enum":["skip","replace","merge"]}},"maxFileSizeMB":{"type":"number"},"maxRows":{"type":"number"}}}}}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/import/{entityType}/validate":{"post":{"summary":"Validate import file (dry run)","tags":["Export/Import"],"description":"\nValidates the import file without saving any data. Use this endpoint to check for errors before actual import.\n\nReturns the same result format as the import endpoint, with dryRun: true.\n      ","parameters":[{"schema":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"]},"in":"path","name":"entityType","required":true,"description":"Entity type to import"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether import completed without critical errors"},"dryRun":{"type":"boolean","description":"Whether this was a validation-only dry run"},"entityType":{"type":"string","enum":["resources","spaces","categories","tags","contacts","groups","type_definitions","message_templates"],"description":"Entity type that was imported"},"stats":{"type":"object","properties":{"created":{"type":"number","description":"Number of entities created"},"updated":{"type":"number","description":"Number of entities updated"},"skipped":{"type":"number","description":"Number of entities skipped (merge strategy)"},"duplicates":{"type":"number","description":"Number of duplicate entries detected"},"errors":{"type":"number","description":"Number of rows with errors"}},"required":["created","updated","skipped","duplicates","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","description":"Row number (1-based, including header)"},"column":{"type":"string","description":"Column name where error occurred"},"value":{"type":"string","description":"Value that caused the error"},"identifier":{"type":"string","description":"Entity identifier (name, key, id)"},"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["INVALID_FORMAT","REQUIRED_FIELD","INVALID_UUID","DUPLICATE_ENTRY","REFERENCE_NOT_FOUND","VALIDATION_ERROR","IMPORT_ERROR","FILE_ERROR"]}},"required":["identifier","message","code"],"additionalProperties":false},"description":"Detailed error information per row"},"processedRows":{"type":"number","description":"Total number of rows processed"},"totalRows":{"type":"number","description":"Total number of rows in file"}},"required":["success","dryRun","entityType","stats","warnings","errors"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/invitations/":{"post":{"summary":"Create invitation","tags":["Invitations"],"description":"Create a new invitation to join the tenant. Sends invitation message via specified channel.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_email":{"type":"string","format":"email","description":"Email address of the invited user"},"recipient_phone":{"type":"string","description":"Phone number of the invited user (E.164 format)"},"role":{"type":"string","enum":["owner","admin","member","guest"],"default":"member","description":"Role to assign to user upon accepting invitation"},"channel":{"type":"string","enum":["email","sms","whatsapp"],"default":"email","description":"Delivery channel for invitation message"},"language":{"type":"string","default":"en","description":"Language for invitation message (ISO 639-1 code)"},"personal_message":{"type":"string","maxLength":500,"description":"Optional personal message from inviter"},"expires_in_hours":{"type":"number","minimum":1,"maximum":168,"default":24,"description":"Hours until invitation expires"}},"anyOf":[{"required":["recipient_email"]},{"required":["recipient_phone"]}],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenant_name":{"type":"string"},"invited_by":{"type":"string","format":"uuid"},"invited_by_name":{"type":"string","nullable":true},"recipient_email":{"type":"string","nullable":true},"recipient_phone":{"type":"string","nullable":true},"code":{"type":"string","description":"Masked code (last 4 chars visible)"},"role":{"type":"string","enum":["owner","admin","member","guest"]},"status":{"type":"string","enum":["pending","sent","opened","accepted","expired","revoked","failed"]},"channel":{"type":"string","enum":["email","sms","whatsapp"]},"language":{"type":"string"},"personal_message":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time","nullable":true},"opened_at":{"type":"string","format":"date-time","nullable":true},"accepted_at":{"type":"string","format":"date-time","nullable":true},"accepted_by":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"invitation_url":{"type":"string","format":"uri","description":"Full invitation URL for the recipient"},"full_code":{"type":"string","description":"Full invitation code (only shown once on creation)"}},"required":["id","tenantId","invited_by","role","status","channel","language","expires_at","created_at","updated_at","invitation_url","full_code"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"get":{"summary":"List invitations","tags":["Invitations"],"description":"List all invitations for the current tenant","parameters":[{"schema":{"type":"string","enum":["pending","sent","opened","accepted","expired","revoked","failed"]},"in":"query","name":"status","required":false},{"schema":{"type":"number","default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenant_name":{"type":"string"},"invited_by":{"type":"string","format":"uuid"},"invited_by_name":{"type":"string","nullable":true},"recipient_email":{"type":"string","nullable":true},"recipient_phone":{"type":"string","nullable":true},"code":{"type":"string","description":"Masked code (last 4 chars visible)"},"role":{"type":"string","enum":["owner","admin","member","guest"]},"status":{"type":"string","enum":["pending","sent","opened","accepted","expired","revoked","failed"]},"channel":{"type":"string","enum":["email","sms","whatsapp"]},"language":{"type":"string"},"personal_message":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time","nullable":true},"opened_at":{"type":"string","format":"date-time","nullable":true},"accepted_at":{"type":"string","format":"date-time","nullable":true},"accepted_by":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","invited_by","role","status","channel","language","expires_at","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/invitations/{id}":{"get":{"summary":"Get invitation","tags":["Invitations"],"description":"Get details of a specific invitation","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenant_name":{"type":"string"},"invited_by":{"type":"string","format":"uuid"},"invited_by_name":{"type":"string","nullable":true},"recipient_email":{"type":"string","nullable":true},"recipient_phone":{"type":"string","nullable":true},"code":{"type":"string","description":"Masked code (last 4 chars visible)"},"role":{"type":"string","enum":["owner","admin","member","guest"]},"status":{"type":"string","enum":["pending","sent","opened","accepted","expired","revoked","failed"]},"channel":{"type":"string","enum":["email","sms","whatsapp"]},"language":{"type":"string"},"personal_message":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time","nullable":true},"opened_at":{"type":"string","format":"date-time","nullable":true},"accepted_at":{"type":"string","format":"date-time","nullable":true},"accepted_by":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","invited_by","role","status","channel","language","expires_at","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Revoke invitation","tags":["Invitations"],"description":"Cancel/revoke a pending invitation","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/invitations/{id}/resend":{"post":{"summary":"Resend invitation","tags":["Invitations"],"description":"Resend an invitation message, optionally changing channel or extending expiry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms","whatsapp"],"description":"Optionally change delivery channel"},"language":{"type":"string","description":"Optionally change language"},"extend_expiry":{"type":"boolean","default":true,"description":"Reset expiry to 24h from now"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenant_name":{"type":"string"},"invited_by":{"type":"string","format":"uuid"},"invited_by_name":{"type":"string","nullable":true},"recipient_email":{"type":"string","nullable":true},"recipient_phone":{"type":"string","nullable":true},"code":{"type":"string","description":"Masked code (last 4 chars visible)"},"role":{"type":"string","enum":["owner","admin","member","guest"]},"status":{"type":"string","enum":["pending","sent","opened","accepted","expired","revoked","failed"]},"channel":{"type":"string","enum":["email","sms","whatsapp"]},"language":{"type":"string"},"personal_message":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time","nullable":true},"opened_at":{"type":"string","format":"date-time","nullable":true},"accepted_at":{"type":"string","format":"date-time","nullable":true},"accepted_by":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenantId","invited_by","role","status","channel","language","expires_at","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/qr-codes/":{"get":{"summary":"List QR codes","tags":["QR Codes"],"description":"Get paginated list of QR codes with optional filters","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["TEXT","URL","LANDING_PAGE","CONTACT","LOCATION","CUSTOM"]},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["LIVE","STATIC"]},"in":"query","name":"renderMode","required":false},{"schema":{"type":"boolean"},"in":"query","name":"isVersioned","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search in name and description"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"createdByUserId","required":false},{"schema":{"type":"string"},"in":"query","name":"linkedType","required":false,"description":"Filter by linked entity type"},{"schema":{"type":"integer"},"in":"query","name":"linkedId","required":false,"description":"Filter by linked entity ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"createdByUserId":{"type":"string","format":"uuid","description":"Creator user UUID"},"name":{"type":"string","description":"QR code name"},"description":{"type":"string","description":"QR code description"},"type":{"type":"string","enum":["TEXT","URL","LANDING_PAGE","CONTACT","LOCATION","CUSTOM"]},"payloadTemplate":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Property type (e.g., LOCATION, TEXT, URL)"},"property":{"type":"string","description":"Property key (e.g., lat, lng, url)"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Property value"}},"required":["type","property","value"]}}],"description":"Content encoded in the QR image"},"metadata":{"type":"object","additionalProperties":true,"description":"App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."},"options":{"type":"object","properties":{"foregroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code foreground","default":"#000000"},"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code background","default":"#FFFFFF"},"size":{"type":"integer","minimum":64,"maximum":4096,"description":"Size dimension in pixels or ems","default":256},"sizeUnit":{"type":"string","enum":["px","em"],"description":"Unit for size dimension","default":"px"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"description":"Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"},"margin":{"type":"integer","minimum":0,"maximum":10,"description":"Margin in module units","default":4},"themeId":{"type":"string","description":"Optional theme identifier"},"printProfile":{"type":"string","enum":["STANDARD","HI_RES_300DPI","HI_RES_600DPI"]},"icon":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether icon overlay is enabled"},"size":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"color":{"type":"string","description":"Hex color for icon (inherits foreground if not set)"},"mediaId":{"type":"string","format":"uuid","description":"UUID of media file for icon image"}},"required":["enabled","size"]}},"required":["foregroundColor","backgroundColor","size","sizeUnit","errorCorrectionLevel","margin","printProfile","icon"]},"renderMode":{"type":"string","enum":["LIVE","STATIC"]},"accessLevel":{"type":"string","enum":["PUBLIC","AUTHENTICATED","API_KEY","PRIVATE"],"description":"Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)","default":"PUBLIC"},"isVersioned":{"type":"boolean","description":"Whether versioning is enabled"},"versionCounter":{"type":"integer","description":"Current version number"},"latestMediaId":{"type":"string","format":"uuid","description":"Latest media file UUID"},"publicUrl":{"type":"string","description":"Public URL for embedding (only if accessLevel is PUBLIC)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by identifier"},"updatedBy":{"type":"string","description":"Updated by identifier"}},"required":["id","uuid","tenantId","createdByUserId","name","type","payloadTemplate","metadata","options","renderMode","accessLevel","isVersioned","versionCounter","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"]}},"required":["data","pagination"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"post":{"summary":"Create QR code","tags":["QR Codes"],"description":"Create a new QR code","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"QR code name"},"description":{"type":"string","description":"QR code description"},"type":{"type":"string","enum":["TEXT","URL","LANDING_PAGE","CONTACT","LOCATION","CUSTOM"]},"payloadTemplate":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Property type (e.g., LOCATION, TEXT, URL)"},"property":{"type":"string","description":"Property key (e.g., lat, lng, url)"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Property value"}},"required":["type","property","value"]}}],"description":"Content encoded in the QR image"},"metadata":{"type":"object","additionalProperties":true,"description":"App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."},"options":{"type":"object","properties":{"foregroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"size":{"type":"integer","minimum":64,"maximum":4096},"sizeUnit":{"type":"string","enum":["px","em"]},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"description":"Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"},"margin":{"type":"integer","minimum":0,"maximum":10},"themeId":{"type":"string"},"printProfile":{"type":"string","enum":["STANDARD","HI_RES_300DPI","HI_RES_600DPI"]},"icon":{"type":"object","properties":{"enabled":{"type":"boolean"},"size":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"color":{"type":"string"},"mediaId":{"type":"string","format":"uuid"}},"required":[]}},"additionalProperties":false},"renderMode":{"type":"string","enum":["LIVE","STATIC"]},"accessLevel":{"type":"string","enum":["PUBLIC","AUTHENTICATED","API_KEY","PRIVATE"],"description":"Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)","default":"PUBLIC"},"isVersioned":{"type":"boolean","description":"Enable versioning"}},"required":["name","type"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"createdByUserId":{"type":"string","format":"uuid","description":"Creator user UUID"},"name":{"type":"string","description":"QR code name"},"description":{"type":"string","description":"QR code description"},"type":{"type":"string","enum":["TEXT","URL","LANDING_PAGE","CONTACT","LOCATION","CUSTOM"]},"payloadTemplate":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Property type (e.g., LOCATION, TEXT, URL)"},"property":{"type":"string","description":"Property key (e.g., lat, lng, url)"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Property value"}},"required":["type","property","value"]}}],"description":"Content encoded in the QR image"},"metadata":{"type":"object","additionalProperties":true,"description":"App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."},"options":{"type":"object","properties":{"foregroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code foreground","default":"#000000"},"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code background","default":"#FFFFFF"},"size":{"type":"integer","minimum":64,"maximum":4096,"description":"Size dimension in pixels or ems","default":256},"sizeUnit":{"type":"string","enum":["px","em"],"description":"Unit for size dimension","default":"px"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"description":"Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"},"margin":{"type":"integer","minimum":0,"maximum":10,"description":"Margin in module units","default":4},"themeId":{"type":"string","description":"Optional theme identifier"},"printProfile":{"type":"string","enum":["STANDARD","HI_RES_300DPI","HI_RES_600DPI"]},"icon":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether icon overlay is enabled"},"size":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"color":{"type":"string","description":"Hex color for icon (inherits foreground if not set)"},"mediaId":{"type":"string","format":"uuid","description":"UUID of media file for icon image"}},"required":["enabled","size"]}},"required":["foregroundColor","backgroundColor","size","sizeUnit","errorCorrectionLevel","margin","printProfile","icon"]},"renderMode":{"type":"string","enum":["LIVE","STATIC"]},"accessLevel":{"type":"string","enum":["PUBLIC","AUTHENTICATED","API_KEY","PRIVATE"],"description":"Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)","default":"PUBLIC"},"isVersioned":{"type":"boolean","description":"Whether versioning is enabled"},"versionCounter":{"type":"integer","description":"Current version number"},"latestMediaId":{"type":"string","format":"uuid","description":"Latest media file UUID"},"publicUrl":{"type":"string","description":"Public URL for embedding (only if accessLevel is PUBLIC)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by identifier"},"updatedBy":{"type":"string","description":"Updated by identifier"}},"required":["id","uuid","tenantId","createdByUserId","name","type","payloadTemplate","metadata","options","renderMode","accessLevel","isVersioned","versionCounter","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/qr-codes/{uuid}":{"get":{"summary":"Get QR code by UUID","tags":["QR Codes"],"description":"Get detailed information about a QR code","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"createdByUserId":{"type":"string","format":"uuid","description":"Creator user UUID"},"name":{"type":"string","description":"QR code name"},"description":{"type":"string","description":"QR code description"},"type":{"type":"string","enum":["TEXT","URL","LANDING_PAGE","CONTACT","LOCATION","CUSTOM"]},"payloadTemplate":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Property type (e.g., LOCATION, TEXT, URL)"},"property":{"type":"string","description":"Property key (e.g., lat, lng, url)"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Property value"}},"required":["type","property","value"]}}],"description":"Content encoded in the QR image"},"metadata":{"type":"object","additionalProperties":true,"description":"App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."},"options":{"type":"object","properties":{"foregroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code foreground","default":"#000000"},"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code background","default":"#FFFFFF"},"size":{"type":"integer","minimum":64,"maximum":4096,"description":"Size dimension in pixels or ems","default":256},"sizeUnit":{"type":"string","enum":["px","em"],"description":"Unit for size dimension","default":"px"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"description":"Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"},"margin":{"type":"integer","minimum":0,"maximum":10,"description":"Margin in module units","default":4},"themeId":{"type":"string","description":"Optional theme identifier"},"printProfile":{"type":"string","enum":["STANDARD","HI_RES_300DPI","HI_RES_600DPI"]},"icon":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether icon overlay is enabled"},"size":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"color":{"type":"string","description":"Hex color for icon (inherits foreground if not set)"},"mediaId":{"type":"string","format":"uuid","description":"UUID of media file for icon image"}},"required":["enabled","size"]}},"required":["foregroundColor","backgroundColor","size","sizeUnit","errorCorrectionLevel","margin","printProfile","icon"]},"renderMode":{"type":"string","enum":["LIVE","STATIC"]},"accessLevel":{"type":"string","enum":["PUBLIC","AUTHENTICATED","API_KEY","PRIVATE"],"description":"Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)","default":"PUBLIC"},"isVersioned":{"type":"boolean","description":"Whether versioning is enabled"},"versionCounter":{"type":"integer","description":"Current version number"},"latestMediaId":{"type":"string","format":"uuid","description":"Latest media file UUID"},"publicUrl":{"type":"string","description":"Public URL for embedding (only if accessLevel is PUBLIC)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by identifier"},"updatedBy":{"type":"string","description":"Updated by identifier"}},"required":["id","uuid","tenantId","createdByUserId","name","type","payloadTemplate","metadata","options","renderMode","accessLevel","isVersioned","versionCounter","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"patch":{"summary":"Update QR code","tags":["QR Codes"],"description":"Update an existing QR code","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"QR code name"},"description":{"type":"string","description":"QR code description"},"type":{"type":"string","enum":["TEXT","URL","LANDING_PAGE","CONTACT","LOCATION","CUSTOM"]},"payloadTemplate":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Property type (e.g., LOCATION, TEXT, URL)"},"property":{"type":"string","description":"Property key (e.g., lat, lng, url)"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Property value"}},"required":["type","property","value"]}}],"description":"Content encoded in the QR image"},"metadata":{"type":"object","additionalProperties":true,"description":"App-level metadata — replaces existing object entirely when provided."},"options":{"type":"object","properties":{"foregroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"size":{"type":"integer","minimum":64,"maximum":4096},"sizeUnit":{"type":"string","enum":["px","em"]},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"description":"Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"},"margin":{"type":"integer","minimum":0,"maximum":10},"themeId":{"type":"string"},"printProfile":{"type":"string","enum":["STANDARD","HI_RES_300DPI","HI_RES_600DPI"]},"icon":{"type":"object","properties":{"enabled":{"type":"boolean"},"size":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"color":{"type":"string"},"mediaId":{"type":"string","format":"uuid"}},"required":[]}},"additionalProperties":false},"renderMode":{"type":"string","enum":["LIVE","STATIC"]},"accessLevel":{"type":"string","enum":["PUBLIC","AUTHENTICATED","API_KEY","PRIVATE"],"description":"Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)","default":"PUBLIC"},"isVersioned":{"type":"boolean","description":"Enable versioning"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"createdByUserId":{"type":"string","format":"uuid","description":"Creator user UUID"},"name":{"type":"string","description":"QR code name"},"description":{"type":"string","description":"QR code description"},"type":{"type":"string","enum":["TEXT","URL","LANDING_PAGE","CONTACT","LOCATION","CUSTOM"]},"payloadTemplate":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Property type (e.g., LOCATION, TEXT, URL)"},"property":{"type":"string","description":"Property key (e.g., lat, lng, url)"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Property value"}},"required":["type","property","value"]}}],"description":"Content encoded in the QR image"},"metadata":{"type":"object","additionalProperties":true,"description":"App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."},"options":{"type":"object","properties":{"foregroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code foreground","default":"#000000"},"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code background","default":"#FFFFFF"},"size":{"type":"integer","minimum":64,"maximum":4096,"description":"Size dimension in pixels or ems","default":256},"sizeUnit":{"type":"string","enum":["px","em"],"description":"Unit for size dimension","default":"px"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"description":"Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"},"margin":{"type":"integer","minimum":0,"maximum":10,"description":"Margin in module units","default":4},"themeId":{"type":"string","description":"Optional theme identifier"},"printProfile":{"type":"string","enum":["STANDARD","HI_RES_300DPI","HI_RES_600DPI"]},"icon":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether icon overlay is enabled"},"size":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"color":{"type":"string","description":"Hex color for icon (inherits foreground if not set)"},"mediaId":{"type":"string","format":"uuid","description":"UUID of media file for icon image"}},"required":["enabled","size"]}},"required":["foregroundColor","backgroundColor","size","sizeUnit","errorCorrectionLevel","margin","printProfile","icon"]},"renderMode":{"type":"string","enum":["LIVE","STATIC"]},"accessLevel":{"type":"string","enum":["PUBLIC","AUTHENTICATED","API_KEY","PRIVATE"],"description":"Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)","default":"PUBLIC"},"isVersioned":{"type":"boolean","description":"Whether versioning is enabled"},"versionCounter":{"type":"integer","description":"Current version number"},"latestMediaId":{"type":"string","format":"uuid","description":"Latest media file UUID"},"publicUrl":{"type":"string","description":"Public URL for embedding (only if accessLevel is PUBLIC)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by identifier"},"updatedBy":{"type":"string","description":"Updated by identifier"}},"required":["id","uuid","tenantId","createdByUserId","name","type","payloadTemplate","metadata","options","renderMode","accessLevel","isVersioned","versionCounter","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Delete QR code","tags":["QR Codes"],"description":"Delete a QR code","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/qr-codes/{uuid}/resolve":{"get":{"summary":"Resolve QR code linked target","tags":["QR Codes"],"description":"Resolve a QR code UUID to its linked PVE entities for trusted application backends.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"qrCode":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"tenantId":{"type":"string","format":"uuid","description":"Tenant UUID"},"createdByUserId":{"type":"string","format":"uuid","description":"Creator user UUID"},"name":{"type":"string","description":"QR code name"},"description":{"type":"string","description":"QR code description"},"type":{"type":"string","enum":["TEXT","URL","LANDING_PAGE","CONTACT","LOCATION","CUSTOM"]},"payloadTemplate":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Property type (e.g., LOCATION, TEXT, URL)"},"property":{"type":"string","description":"Property key (e.g., lat, lng, url)"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Property value"}},"required":["type","property","value"]}}],"description":"Content encoded in the QR image"},"metadata":{"type":"object","additionalProperties":true,"description":"App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."},"options":{"type":"object","properties":{"foregroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code foreground","default":"#000000"},"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code background","default":"#FFFFFF"},"size":{"type":"integer","minimum":64,"maximum":4096,"description":"Size dimension in pixels or ems","default":256},"sizeUnit":{"type":"string","enum":["px","em"],"description":"Unit for size dimension","default":"px"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"description":"Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"},"margin":{"type":"integer","minimum":0,"maximum":10,"description":"Margin in module units","default":4},"themeId":{"type":"string","description":"Optional theme identifier"},"printProfile":{"type":"string","enum":["STANDARD","HI_RES_300DPI","HI_RES_600DPI"]},"icon":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether icon overlay is enabled"},"size":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"color":{"type":"string","description":"Hex color for icon (inherits foreground if not set)"},"mediaId":{"type":"string","format":"uuid","description":"UUID of media file for icon image"}},"required":["enabled","size"]}},"required":["foregroundColor","backgroundColor","size","sizeUnit","errorCorrectionLevel","margin","printProfile","icon"]},"renderMode":{"type":"string","enum":["LIVE","STATIC"]},"accessLevel":{"type":"string","enum":["PUBLIC","AUTHENTICATED","API_KEY","PRIVATE"],"description":"Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)","default":"PUBLIC"},"isVersioned":{"type":"boolean","description":"Whether versioning is enabled"},"versionCounter":{"type":"integer","description":"Current version number"},"latestMediaId":{"type":"string","format":"uuid","description":"Latest media file UUID"},"publicUrl":{"type":"string","description":"Public URL for embedding (only if accessLevel is PUBLIC)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by identifier"},"updatedBy":{"type":"string","description":"Updated by identifier"}},"required":["id","uuid","tenantId","createdByUserId","name","type","payloadTemplate","metadata","options","renderMode","accessLevel","isVersioned","versionCounter","createdAt","updatedAt"]},"links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"qrCodeId":{"type":"integer","description":"QR code ID"},"linkedType":{"type":"string","enum":["space","resource","contact","user","calendar_entry"],"description":"Linked entity type"},"linkedId":{"type":"integer","description":"Linked entity ID"},"linkedUuid":{"type":"string","format":"uuid","description":"Linked entity UUID"},"permissionSource":{"type":"string","description":"Permission source description"},"inheritsPermissions":{"type":"boolean","description":"Whether permissions are inherited"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"createdByUserId":{"type":"string","format":"uuid","description":"Creator user UUID"}},"required":["id","uuid","qrCodeId","linkedType","inheritsPermissions","createdAt","updatedAt"]}},"primaryTarget":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["space","resource","contact","user","calendar_entry"],"description":"Primary linked entity type resolved from QR assignments"},"id":{"type":"integer","description":"Linked entity numeric ID when available"},"uuid":{"type":"string","format":"uuid","description":"Linked entity UUID when available"},"linkId":{"type":"integer","description":"QR link row ID that produced this target"},"permissionSource":{"type":"string","description":"Permission inheritance source for this assignment"},"inheritsPermissions":{"type":"boolean","description":"Whether this assignment inherits entity permissions"}},"required":["type","linkId","inheritsPermissions"],"additionalProperties":false},{"type":"null"}],"description":"First linked target for convenience; clients should inspect links when multiple assignments exist"}},"required":["qrCode","links","primaryTarget"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/qr-codes/{uuid}/download":{"get":{"summary":"Download QR code image","tags":["QR Codes"],"description":"Download QR code as PNG or SVG","parameters":[{"schema":{"type":"string","enum":["png","svg"],"default":"png"},"in":"query","name":"format","required":false,"description":"Output format"},{"schema":{"type":"integer","minimum":64,"maximum":4096},"in":"query","name":"size","required":false,"description":"Override size"},{"schema":{"type":"string"},"in":"query","name":"theme","required":false,"description":"Override theme"},{"schema":{"type":"string"},"in":"query","name":"downloadToken","required":false,"description":"Ephemeral download token"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"QR code image","content":{"application/json":{"schema":{"description":"QR code image","type":"string","format":"binary"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/qr-codes/{uuid}/regenerate":{"post":{"summary":"Regenerate QR code","tags":["QR Codes"],"description":"Force regeneration of static QR code image","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Force regeneration even if unchanged","default":false}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"regenerated":{"type":"boolean","description":"Whether regeneration was performed"},"versionNumber":{"type":"integer","description":"New version number if versioned"},"mediaId":{"type":"string","format":"uuid","description":"New media file UUID"},"checksum":{"type":"string","description":"SHA-256 checksum"}},"required":["regenerated"]}},"required":["data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/qr-codes/{uuid}/versions":{"get":{"summary":"Get QR code versions","tags":["QR Codes"],"description":"Get version history for a QR code","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"qrCodeId":{"type":"integer","description":"Parent QR code ID"},"versionNumber":{"type":"integer","description":"Version number"},"mediaFileId":{"type":"string","format":"uuid","description":"Media file UUID"},"checksum":{"type":"string","description":"SHA-256 checksum of rendered image"},"optionsSnapshot":{"type":"object","properties":{"foregroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code foreground","default":"#000000"},"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"Hex color for QR code background","default":"#FFFFFF"},"size":{"type":"integer","minimum":64,"maximum":4096,"description":"Size dimension in pixels or ems","default":256},"sizeUnit":{"type":"string","enum":["px","em"],"description":"Unit for size dimension","default":"px"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"description":"Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"},"margin":{"type":"integer","minimum":0,"maximum":10,"description":"Margin in module units","default":4},"themeId":{"type":"string","description":"Optional theme identifier"},"printProfile":{"type":"string","enum":["STANDARD","HI_RES_300DPI","HI_RES_600DPI"]},"icon":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether icon overlay is enabled"},"size":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"color":{"type":"string","description":"Hex color for icon (inherits foreground if not set)"},"mediaId":{"type":"string","format":"uuid","description":"UUID of media file for icon image"}},"required":["enabled","size"]}},"required":["foregroundColor","backgroundColor","size","sizeUnit","errorCorrectionLevel","margin","printProfile","icon"]},"payloadSnapshot":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Property type (e.g., LOCATION, TEXT, URL)"},"property":{"type":"string","description":"Property key (e.g., lat, lng, url)"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Property value"}},"required":["type","property","value"]}}]},"renderDurationMs":{"type":"integer","description":"Render duration in milliseconds"},"fileSizeBytes":{"type":"integer","description":"File size in bytes"},"imageFormat":{"type":"string","enum":["png","svg"],"description":"Image format"},"renderedAt":{"type":"string","format":"date-time","description":"Render timestamp"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}},"required":["id","uuid","qrCodeId","versionNumber","checksum","optionsSnapshot","payloadSnapshot","renderedAt","createdAt"]}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/qr-codes/{uuid}/links":{"get":{"summary":"Get QR code links","tags":["QR Codes"],"description":"Get entities linked to a QR code","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"qrCodeId":{"type":"integer","description":"QR code ID"},"linkedType":{"type":"string","enum":["space","resource","contact","user","calendar_entry"],"description":"Linked entity type"},"linkedId":{"type":"integer","description":"Linked entity ID"},"linkedUuid":{"type":"string","format":"uuid","description":"Linked entity UUID"},"permissionSource":{"type":"string","description":"Permission source description"},"inheritsPermissions":{"type":"boolean","description":"Whether permissions are inherited"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"createdByUserId":{"type":"string","format":"uuid","description":"Creator user UUID"}},"required":["id","uuid","qrCodeId","linkedType","inheritsPermissions","createdAt","updatedAt"]}}},"required":["data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"post":{"summary":"Link QR code to entity","tags":["QR Codes"],"description":"Create a link between QR code and another entity","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"linkedType":{"type":"string","enum":["space","resource","contact","user","calendar_entry"],"description":"Entity type to link"},"linkedId":{"type":"integer","description":"Entity ID to link"},"linkedUuid":{"type":"string","format":"uuid","description":"Entity UUID to link"},"permissionSource":{"type":"string","description":"Permission source description"},"inheritsPermissions":{"type":"boolean","description":"Inherit permissions from linked entity","default":true}},"required":["linkedType"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","description":"Database ID"},"uuid":{"type":"string","format":"uuid","description":"UUID identifier"},"qrCodeId":{"type":"integer","description":"QR code ID"},"linkedType":{"type":"string","enum":["space","resource","contact","user","calendar_entry"],"description":"Linked entity type"},"linkedId":{"type":"integer","description":"Linked entity ID"},"linkedUuid":{"type":"string","format":"uuid","description":"Linked entity UUID"},"permissionSource":{"type":"string","description":"Permission source description"},"inheritsPermissions":{"type":"boolean","description":"Whether permissions are inherited"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"createdByUserId":{"type":"string","format":"uuid","description":"Creator user UUID"}},"required":["id","uuid","qrCodeId","linkedType","inheritsPermissions","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/qr-codes/{uuid}/links/{linkId}":{"delete":{"summary":"Unlink QR code from entity","tags":["QR Codes"],"description":"Delete a link between QR code and entity","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"uuid","required":true},{"schema":{"type":"integer"},"in":"path","name":"linkId","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/info-tags/":{"get":{"summary":"List info tags","tags":["infotags"],"description":"Returns all info tags accessible to the current tenant (own + system-wide).","parameters":[{"schema":{"type":"string","maxLength":200},"in":"query","name":"q","required":false},{"schema":{"type":"string","minLength":2,"maxLength":5},"in":"query","name":"locale","required":false},{"schema":{"type":"number","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string","pattern":"^[a-z0-9_.-]+$"},"title":{"type":"string"},"description":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false}},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","title","description","created_at","updated_at"]}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["data","total","limit","offset"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"post":{"summary":"Create info tag","tags":["infotags"],"description":"Creates a new tenant-scoped info tag for contextual help content and usage guidance.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","title","description"],"properties":{"key":{"type":"string","pattern":"^[a-z0-9_.-]+$","minLength":3,"maxLength":200},"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000},"examples":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false}}},"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string","pattern":"^[a-z0-9_.-]+$"},"title":{"type":"string"},"description":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false}},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","title","description","created_at","updated_at"]}},"required":["data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}}},"/api/v1/secure/info-tags/{id}":{"get":{"summary":"Get info tag by ID","tags":["infotags"],"description":"Returns a single info tag by UUID when it is accessible to the current tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string","pattern":"^[a-z0-9_.-]+$"},"title":{"type":"string"},"description":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false}},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","title","description","created_at","updated_at"]}},"required":["data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"patch":{"summary":"Update info tag","tags":["infotags"],"description":"Updates the editable content and localized fields of an existing info tag.","requestBody":{"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000},"examples":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false}}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"key":{"type":"string","pattern":"^[a-z0-9_.-]+$"},"title":{"type":"string"},"description":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"translations_i18n":{"type":"object","additionalProperties":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false}},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","title","description","created_at","updated_at"]}},"required":["data"]}}}},"400":{"description":"400 Bad Request - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[400]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"400 Bad Request - Validation error"}}}},"401":{"description":"401 Unauthorized - Authentication required or failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["AUTHENTICATION_ERROR","AUTH_REQUIRED"],"description":"Error code for authentication errors","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[401]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"401 Unauthorized - Authentication required or failed"}}}},"403":{"description":"403 Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["PERMISSION_ERROR","FORBIDDEN"],"description":"Error code for permission errors","example":"PERMISSION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[403]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"403 Forbidden - Insufficient permissions"}}}},"404":{"description":"404 Not Found - Resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NOT_FOUND","RESOURCE_NOT_FOUND"],"description":"Error code for not found errors","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[404]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"404 Not Found - Resource does not exist"}}}},"409":{"description":"409 Conflict - Resource already exists or conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CONFLICT","DUPLICATE_RESOURCE"],"description":"Error code for conflict errors","example":"CONFLICT"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[409]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"409 Conflict - Resource already exists or conflict"}}}},"422":{"description":"422 Unprocessable Entity - Validation error with details","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Error code for validation errors with details","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[422]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"schemaPath":{"type":"string"},"keyword":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validation error parameters (structure varies by keyword)"},"message":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"422 Unprocessable Entity - Validation error with details"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["INTERNAL_ERROR","SERVER_ERROR"],"description":"Error code for server errors","example":"INTERNAL_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","enum":[500]},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false,"description":"500 Internal Server Error"}}}}}},"delete":{"summary":"Delete info tag","tags":["infotags"],"description":"Soft-deletes an info tag so it is no longer returned in tenant help-content lookups.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Info tag deleted successfully"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)","example":"AUTHENTICATION_ERROR"},"message":{"type":"string","description":"Human-readable error message"},"statusCode":{"type":"number","description":"HTTP status code","example":400},"requestId":{"type":"string","nullable":true,"description":"Request tracking ID"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional error context (e.g., validation errors)"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred"}},"required":["error","message","statusCode","timestamp"],"additionalProperties":false}}}}}}}},"servers":[{"url":"https://pve-api-int.pve.ch","description":"API server"},{"url":"http://localhost:3000","description":"Development server (localhost)"}],"tags":[{"name":"Auth","description":"Authentication and authorization endpoints"},{"name":"API Keys","description":"API key authentication and management for programmatic access"},{"name":"Application Accounts","description":"Application service accounts for anonymous/public operations"},{"name":"Users","description":"Manage users and user profiles within tenants"},{"name":"Tenants","description":"Manage tenants (organizations) and tenant configuration"},{"name":"Groups","description":"Manage permission groups and group memberships"},{"name":"Group Members","description":"Manage user assignments to permission groups"},{"name":"User Groups","description":"Get user permissions from group memberships"},{"name":"Spaces","description":"Manage spaces (rooms, buildings, locations) with member management and filtering"},{"name":"Space Members","description":"Manage space member assignments and roles (manager, reader)"},{"name":"Resources","description":"Manage resources (equipment, people, vehicles, etc.) with filtering, pagination, and taxonomy support"},{"name":"Resource Members","description":"Manage resource memberships and delegation"},{"name":"Resource Move Requests","description":"Resource move workflow between spaces (request, approve, reject)"},{"name":"Tags","description":"Manage tags for organizing entities (resources, spaces, groups, tenants)"},{"name":"Categories","description":"Manage hierarchical categories with multi-language support"},{"name":"Type Definitions","description":"Manage entity type definitions and validation schemas"},{"name":"Media","description":"File uploads, media management, thumbnails, and entity-media relationships"},{"name":"Messaging","description":"Messaging and communication services"},{"name":"Calendar","description":"Calendar and event management services"},{"name":"Settings","description":"Tenant and user settings management"},{"name":"Search","description":"Global search across entities and resources"},{"name":"Features","description":"Feature flags and feature enablement management"},{"name":"Geo-Location","description":"Geo-location services (address lookup, coordinates, autocomplete)"},{"name":"Countries (Public)","description":"Public country reference data with flags and codes"},{"name":"Languages (Public)","description":"Languages (Public) endpoints"},{"name":"Timezones (Public)","description":"Timezones (Public) endpoints"},{"name":"Phone Validation (Public)","description":"Phone Validation (Public) endpoints"},{"name":"System","description":"System-level operations and infrastructure endpoints"},{"name":"Admin","description":"Admin endpoints"},{"name":"Admin Notifications","description":"Admin Notifications endpoints"},{"name":"AI Providers","description":"AI Providers endpoints"},{"name":"AI Translation","description":"AI Translation endpoints"},{"name":"Approval","description":"Approval endpoints"},{"name":"Audit Logs","description":"Audit Logs endpoints"},{"name":"Calendar Admin","description":"Calendar Admin endpoints"},{"name":"Calendar Booking","description":"Calendar Booking endpoints"},{"name":"Calendar Groups","description":"Calendar Groups endpoints"},{"name":"Chat","description":"Chat endpoints"},{"name":"Chat Admin","description":"Chat Admin endpoints"},{"name":"Contacts","description":"Contacts endpoints"},{"name":"currencies","description":"currencies endpoints"},{"name":"Domains","description":"Domains endpoints"},{"name":"Export/Import","description":"Export/Import endpoints"},{"name":"Feedback","description":"User feedback and support request management"},{"name":"Files","description":"Files endpoints"},{"name":"Flags (Public)","description":"Flags (Public) endpoints"},{"name":"infotags","description":"infotags endpoints"},{"name":"Invitations","description":"Invitations endpoints"},{"name":"Jobs","description":"Jobs endpoints"},{"name":"MCP","description":"MCP endpoints"},{"name":"Media Settings","description":"Media Settings endpoints"},{"name":"Notifications","description":"Notifications endpoints"},{"name":"phone-codes","description":"phone-codes endpoints"},{"name":"Profile","description":"Profile endpoints"},{"name":"Public","description":"Public endpoints"},{"name":"QR Codes","description":"QR Codes endpoints"},{"name":"Stats","description":"Stats endpoints"},{"name":"Storage","description":"Storage endpoints"},{"name":"System Chat","description":"System Chat endpoints"},{"name":"System Notifications","description":"System Notifications endpoints"},{"name":"Tenant Domains","description":"Tenant Domains endpoints"},{"name":"Tenant Metrics","description":"Tenant Metrics endpoints"},{"name":"Tenant Rate Limits","description":"Tenant Rate Limits endpoints"},{"name":"Tenant Settings","description":"Tenant Settings endpoints"},{"name":"Webhooks","description":"Webhooks endpoints"}]}