{
  "openapi": "3.0.3",
  "info": {
    "title": "AuthLX Security & Licensing API",
    "description": "AuthLX is a developer-first authentication and software licensing platform providing cryptographic Hardware ID (HWID) locking, user session management, license key validation, and reseller controls for desktop applications.",
    "version": "2.0.0",
    "contact": {
      "name": "AuthLX Support",
      "url": "https://authlx.com/docs",
      "email": "support@authlx.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://authlx.com/terms"
    }
  },
  "x-service-info": {
    "categories": [
      "developer-tools",
      "authentication",
      "licensing",
      "security",
      "commerce"
    ]
  },
  "x-deprecation-policy": {
    "policy": "12-month deprecation lifecycle with IETF RFC 8594 Deprecation and Sunset response headers.",
    "documentation": "https://authlx.com/deprecation-policy",
    "sunset_timeline_days": 365,
    "header_standards": ["Deprecation", "Sunset", "Link"]
  },
  "x-versioning-policy": {
    "type": "uri-path",
    "supported_versions": ["v1", "v2"],
    "default_version": "v2",
    "documentation": "https://authlx.com/deprecation-policy"
  },
  "x-rate-limit-info": {
    "standard": "IETF draft-7 RateLimit-* headers",
    "limit": 100,
    "window_seconds": 60
  },
  "servers": [
    {
      "url": "https://api.authlx.com",
      "description": "Production API Server"
    },
    {
      "url": "https://authlx.com",
      "description": "Primary Web Domain"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getSystemHealth",
        "summary": "System Health Check",
        "description": "Check if the AuthLX API cluster, database connections, and real-time MQTT messaging broker are operational.",
        "responses": {
          "200": {
            "description": "API is operational and healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "operationId": "agentPaymentChallenge",
        "summary": "x402 & MPP Agent Payment Challenge",
        "description": "Agent payment challenge endpoint returning 402 Payment Required for machine-to-machine requests.",
        "x-payment-info": {
          "intent": "charge",
          "method": "stripe",
          "amount": 0.001,
          "currency": "USDC",
          "description": "AuthLX Machine-to-Machine API Agent Access"
        },
        "responses": {
          "402": {
            "$ref": "#/components/responses/Error402"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/client/plans": {
      "get": {
        "operationId": "getSubscriptionPlans",
        "summary": "Get Subscription Plans & Pricing",
        "description": "Retrieve available subscription tiers, feature quotas, and pricing details for AuthLX developer accounts.",
        "responses": {
          "200": {
            "description": "List of available subscription plans",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlansResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/checkout": {
      "post": {
        "operationId": "createCheckoutSession",
        "summary": "Create Checkout Session",
        "description": "Create a Stripe payable checkout session for purchasing license quotas, subscriptions, and reseller balances.",
        "requestBody": {
          "required": true,
          "description": "Selected plan name and billing period",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session initialized successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutSessionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/client/init": {
      "post": {
        "operationId": "clientInitApp",
        "summary": "Initialize Client SDK Session",
        "description": "Initialize application context and verify active status with App ID and Secret.",
        "requestBody": {
          "required": true,
          "description": "Application credentials for handshake",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientInitRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application initialized successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientInitResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/client/verify-session": {
      "post": {
        "operationId": "verifyClientSession",
        "summary": "Verify User Session & HWID",
        "description": "Verify an active user session token, validate hardware lock integrity, and retrieve license entitlement data.",
        "requestBody": {
          "required": true,
          "description": "Session token and application credentials",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifySessionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session token is valid and active",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifySessionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/client/login": {
      "post": {
        "operationId": "clientLoginV1",
        "summary": "End-User Client Login (v1)",
        "description": "Authenticate an end-user into an application, bind hardware identifier (HWID), and return a scoped session token.",
        "requestBody": {
          "required": true,
          "description": "User credentials, App ID, and client hardware fingerprint",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientLoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User authenticated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientLoginResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/client/register": {
      "post": {
        "operationId": "clientRegister",
        "summary": "End-User Client Registration",
        "description": "Register a new application user account and optionally redeem an initial license key.",
        "requestBody": {
          "required": true,
          "description": "Registration payload with username, password, email, and HWID",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientRegisterRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User registered and provisioned successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientRegisterResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "409": {
            "$ref": "#/components/responses/Error400"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/client/activate": {
      "post": {
        "operationId": "activateLicenseKey",
        "summary": "Activate Software License Key",
        "description": "Redeem a license key against an authenticated user account to extend subscription duration or unlock tiers.",
        "requestBody": {
          "required": true,
          "description": "App credentials, username, and license key string",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LicenseActivateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "License activated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LicenseActivateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v2/client/login": {
      "post": {
        "operationId": "clientLoginV2",
        "summary": "Military-Grade Client Login (v2 HMAC)",
        "description": "High-security v2 login endpoint enforcing cryptographic HMAC-SHA256 request signatures, nonces, and anti-tamper timestamp checks.",
        "parameters": [
          {
            "name": "x-signature",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 signature of request body using App Secret",
            "schema": { "type": "string", "example": "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e" }
          },
          {
            "name": "x-timestamp",
            "in": "header",
            "required": true,
            "description": "Unix timestamp in milliseconds for replay protection",
            "schema": { "type": "string", "example": "1788192000000" }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Encrypted v2 payload with nonce and credentials",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V2ClientLoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "V2 Authenticated session token and entitlements",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2ClientLoginResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/sandbox/auth": {
      "post": {
        "operationId": "verifySandboxSession",
        "summary": "Zero-Auth Sandbox Authentication Handshake",
        "description": "Test authentication handshake for autonomous AI agents and evaluation bots without requiring an active database account.",
        "requestBody": {
          "required": true,
          "description": "Sandbox credentials",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SandboxAuthRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sandbox handshake verified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxAuthResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    },
    "/api/v1/client/logout": {
      "post": {
        "operationId": "clientLogout",
        "summary": "Client User Logout",
        "description": "Terminate an active user session and invalidate the local token.",
        "requestBody": {
          "required": true,
          "description": "Session token to terminate",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientLogoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session terminated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientLogoutResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Provide user session token or developer JWT token."
      },
      "HmacAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-signature",
        "description": "HMAC-SHA256 signature of the payload using the App Secret Key."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "Typed Error Model for 4xx and 5xx API Responses (RFC 9457 / RFC 7807 compliant)",
        "required": ["status", "error", "code", "message", "hint", "docs_url", "type", "timestamp"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["fail", "error"],
            "example": "fail"
          },
          "error": {
            "type": "string",
            "description": "Machine-readable uppercase error token",
            "example": "UNAUTHORIZED"
          },
          "code": {
            "type": "integer",
            "description": "HTTP status code",
            "example": 401
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of error",
            "example": "Invalid or expired session token."
          },
          "hint": {
            "type": "string",
            "description": "Actionable resolution instruction for AI agents and developer clients",
            "example": "Provide a valid session token in Authorization header or authenticate via /api/v1/client/login."
          },
          "docs_url": {
            "type": "string",
            "format": "uri",
            "example": "https://authlx.com/docs"
          },
          "type": {
            "type": "string",
            "format": "uri",
            "example": "https://authlx.com/errors/unauthorized"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-31T23:25:00.000Z"
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 / RFC 7807 Application Problem Details Error Model",
        "required": ["type", "title", "status", "detail"],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "example": "https://authlx.com/errors/unauthorized"
          },
          "title": {
            "type": "string",
            "example": "Unauthorized"
          },
          "status": {
            "type": "integer",
            "example": 401
          },
          "detail": {
            "type": "string",
            "example": "Invalid or expired session token."
          },
          "instance": {
            "type": "string",
            "example": "/api/v1/client/verify-session"
          },
          "code": {
            "type": "string",
            "example": "UNAUTHORIZED"
          },
          "hint": {
            "type": "string",
            "example": "Provide a valid session token in Authorization header."
          },
          "docs_url": {
            "type": "string",
            "format": "uri",
            "example": "https://authlx.com/docs"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-31T23:25:00.000Z"
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "message"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "message": { "type": "string", "example": "Auth Backend is healthy" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "PlanItem": {
        "type": "object",
        "required": ["id", "name", "price", "max_apps", "max_users_per_app"],
        "properties": {
          "id": { "type": "string", "example": "dev_yearly" },
          "name": { "type": "string", "example": "Developer Plan" },
          "price": { "type": "number", "example": 15.00 },
          "currency": { "type": "string", "example": "USD" },
          "period": { "type": "string", "enum": ["monthly", "yearly", "lifetime"], "example": "yearly" },
          "max_apps": { "type": "integer", "example": 7 },
          "max_users_per_app": { "type": "integer", "example": 500 },
          "features": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["7 Applications", "500 Users per App", "HWID Locking", "Priority Support"]
          }
        }
      },
      "PlansResponse": {
        "type": "object",
        "required": ["status", "data"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PlanItem" }
          }
        }
      },
      "CheckoutRequest": {
        "type": "object",
        "required": ["plan_name"],
        "properties": {
          "plan_name": { "type": "string", "example": "developer" },
          "period": { "type": "string", "enum": ["monthly", "yearly"], "example": "yearly" }
        }
      },
      "CheckoutSessionResponse": {
        "type": "object",
        "required": ["status", "url", "sessionId"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "url": { "type": "string", "format": "uri", "example": "https://checkout.stripe.com/c/pay/cs_live_..." },
          "sessionId": { "type": "string", "example": "cs_live_12345" }
        }
      },
      "ClientInitRequest": {
        "type": "object",
        "required": ["app_id", "secret"],
        "properties": {
          "app_id": { "type": "string", "example": "app_live_9x8f2a1b" },
          "secret": { "type": "string", "example": "sec_live_k92m0x7q" },
          "version": { "type": "string", "example": "2.0" }
        }
      },
      "ClientInitResponse": {
        "type": "object",
        "required": ["status", "session_id"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "session_id": { "type": "string", "example": "init_98127391" },
          "app_name": { "type": "string", "example": "My Desktop App" },
          "status_code": { "type": "string", "example": "active" }
        }
      },
      "VerifySessionRequest": {
        "type": "object",
        "required": ["token", "app_id"],
        "properties": {
          "token": { "type": "string", "description": "Active session JWT or session ID" },
          "app_id": { "type": "string", "description": "Registered Application ID" },
          "hwid": { "type": "string", "description": "Optional hardware fingerprint for continuous locking" }
        }
      },
      "VerifySessionResponse": {
        "type": "object",
        "required": ["status", "valid", "user_id"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "valid": { "type": "boolean", "example": true },
          "user_id": { "type": "string", "example": "usr_9981b2" },
          "username": { "type": "string", "example": "demo_user" },
          "expiry": { "type": "string", "format": "date-time" },
          "subscription_tier": { "type": "string", "example": "pro" }
        }
      },
      "ClientLoginRequest": {
        "type": "object",
        "required": ["app_id", "secret", "username", "password", "hwid"],
        "properties": {
          "app_id": { "type": "string", "example": "app_live_9x8f2a1b" },
          "secret": { "type": "string", "example": "sec_live_k92m0x7q" },
          "username": { "type": "string", "example": "demo_user" },
          "password": { "type": "string", "example": "password123" },
          "hwid": { "type": "string", "example": "HWID-8F92-4A1C-99B2" }
        }
      },
      "ClientLoginResponse": {
        "type": "object",
        "required": ["status", "token", "session_id"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "token": { "type": "string", "description": "Signed session token" },
          "session_id": { "type": "string", "example": "sess_8912739182" },
          "expiry": { "type": "string", "format": "date-time" },
          "user": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "username": { "type": "string" },
              "hwid": { "type": "string" },
              "role": { "type": "string" }
            }
          }
        }
      },
      "ClientRegisterRequest": {
        "type": "object",
        "required": ["app_id", "secret", "username", "password", "hwid"],
        "properties": {
          "app_id": { "type": "string", "example": "app_live_9x8f2a1b" },
          "secret": { "type": "string", "example": "sec_live_k92m0x7q" },
          "username": { "type": "string", "example": "new_user" },
          "password": { "type": "string", "example": "SecurePass123!" },
          "email": { "type": "string", "format": "email", "example": "user@example.com" },
          "hwid": { "type": "string", "example": "HWID-8F92-4A1C-99B2" },
          "license_key": { "type": "string", "description": "Optional initial activation key", "example": "AUTHLX-PRO-XXXX" }
        }
      },
      "ClientRegisterResponse": {
        "type": "object",
        "required": ["status", "message", "user_id"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "message": { "type": "string", "example": "User account created successfully" },
          "user_id": { "type": "string", "example": "usr_99182a" }
        }
      },
      "LicenseActivateRequest": {
        "type": "object",
        "required": ["app_id", "secret", "username", "license_key"],
        "properties": {
          "app_id": { "type": "string", "example": "app_live_9x8f2a1b" },
          "secret": { "type": "string", "example": "sec_live_k92m0x7q" },
          "username": { "type": "string", "example": "demo_user" },
          "license_key": { "type": "string", "example": "AUTHLX-YEARLY-99A1-BB22" }
        }
      },
      "LicenseActivateResponse": {
        "type": "object",
        "required": ["status", "message", "expires_at"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "message": { "type": "string", "example": "License successfully activated" },
          "subscription_tier": { "type": "string", "example": "pro" },
          "expires_at": { "type": "string", "format": "date-time" }
        }
      },
      "V2ClientLoginRequest": {
        "type": "object",
        "required": ["app_id", "username", "password", "hwid", "nonce"],
        "properties": {
          "app_id": { "type": "string", "example": "app_live_9x8f2a1b" },
          "username": { "type": "string", "example": "demo_user" },
          "password": { "type": "string", "example": "password123" },
          "hwid": { "type": "string", "example": "HWID-8F92-4A1C-99B2" },
          "nonce": { "type": "string", "example": "nonce_91823719" }
        }
      },
      "V2ClientLoginResponse": {
        "type": "object",
        "required": ["status", "token", "signature"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "token": { "type": "string", "description": "Encrypted JWT session" },
          "signature": { "type": "string", "description": "Server-signed HMAC response verification" },
          "expires_at": { "type": "string", "format": "date-time" }
        }
      },
      "SandboxAuthRequest": {
        "type": "object",
        "required": ["app_id", "username", "hwid"],
        "properties": {
          "app_id": { "type": "string", "example": "sandbox_demo" },
          "username": { "type": "string", "example": "agent_evaluator" },
          "hwid": { "type": "string", "example": "HWID-SANDBOX-TEST" }
        }
      },
      "SandboxAuthResponse": {
        "type": "object",
        "required": ["status", "sandbox", "token"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "sandbox": { "type": "boolean", "example": true },
          "token": { "type": "string", "example": "sbx_test_token_89123" },
          "entitlements": {
            "type": "object",
            "properties": {
              "plan": { "type": "string", "example": "free_developer" },
              "features": {
                "type": "array",
                "items": { "type": "string" },
                "example": ["hwid_lock", "unlimited_logins", "instant_reseller"]
              }
            }
          }
        }
      },
      "ClientLogoutRequest": {
        "type": "object",
        "required": ["app_id", "token"],
        "properties": {
          "app_id": { "type": "string", "example": "app_live_9x8f2a1b" },
          "token": { "type": "string", "example": "sess_8912739182" }
        }
      },
      "ClientLogoutResponse": {
        "type": "object",
        "required": ["status", "message"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "message": { "type": "string", "example": "Session successfully terminated" }
        }
      }
    },
    "responses": {
      "Error400": {
        "description": "Bad Request — Invalid parameters or missing payload attributes",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "Error401": {
        "description": "Unauthorized — Missing, invalid, or expired credentials",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "Error402": {
        "description": "Payment Required — Agent machine payment or quota renewal required",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "Error403": {
        "description": "Forbidden — Quota limit reached or permission denied",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "Error404": {
        "description": "Not Found — Requested resource or endpoint does not exist",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "Error429": {
        "description": "Rate Limited — Too many requests within rate limit window",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "Error500": {
        "description": "Internal Server Error — Unexpected backend failure",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      }
    }
  }
}