{"openapi":"3.1.0","info":{"title":"BadgerClaw API","version":"0.1.0"},"paths":{"/_matrix/push/v1/notify":{"post":{"tags":["push"],"summary":"Push Notify","description":"Proxy push notification requests to Sygnal gateway","operationId":"push_notify__matrix_push_v1_notify_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/_matrix/push/v1/health":{"get":{"tags":["push"],"summary":"Push Health","description":"Health check for push gateway proxy","operationId":"push_health__matrix_push_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"tags":["health"],"summary":"Root / load balancer health check","description":"Root endpoint for Load Balancer health checks","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootResponse"}}}}}}},"/health/kms":{"get":{"tags":["health"],"summary":"KMS health check","description":"Check KMS configuration status","operationId":"health_kms_health_kms_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KmsHealthResponse"}}}}}}},"/health":{"get":{"tags":["health"],"summary":"Basic health check","description":"Basic health check that doesn't require database access","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/health/db":{"get":{"tags":["health"],"summary":"Database health check","description":"Database health check","operationId":"health_check_db_health_db_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DbHealthResponse"}}}}}}},"/health/redis":{"get":{"tags":["health"],"summary":"Redis health check","description":"Redis health check","operationId":"health_check_redis_health_redis_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedisHealthResponse"}}}}}}},"/health/push":{"get":{"tags":["health"],"summary":"Push notification service health check","description":"Push notification service health check","operationId":"health_check_push_health_push_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushHealthResponse"}}}}}}},"/debug/apns-config":{"get":{"tags":["health"],"summary":"Debug Apns Config","description":"Debug endpoint to check APNs configuration (admin only)","operationId":"debug_apns_config_debug_apns_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/test-ios":{"get":{"tags":["health"],"summary":"Test Ios","description":"Test endpoint for iOS app","operationId":"test_ios_test_ios_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/debug/matrix-secret-storage/{user_id}":{"get":{"tags":["health"],"summary":"Debug Matrix Secret Storage","description":"Test Matrix secret storage setup for a user (admin only)","operationId":"debug_matrix_secret_storage_debug_matrix_secret_storage__user_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/test/recovery-key/{user_id}":{"get":{"tags":["health"],"summary":"Test Recovery Key","description":"Test recovery key creation for a user (admin only)","operationId":"test_recovery_key_test_recovery_key__user_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/signup":{"post":{"tags":["user"],"summary":"Register a new user","description":"Register a new user (atomic: Cognito + DB + Matrix).\n\n1. (Optional) Apple DeviceCheck: reject if bit0 already set on device\n2. Validates email and username availability\n3. Creates Cognito account (sends verification OTP to email)\n4. Assigns user to Cognito 'user' group\n5. Creates local DB record\n6. Creates Matrix account via Synapse Admin API\n7. (Optional) Marks DeviceCheck bit0 = True for this device","operationId":"signup_api_v1_user_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/signup/verify":{"post":{"tags":["user"],"summary":"Verify email with OTP","description":"Verify email with OTP code sent by Cognito.\n\nAfter verification, sets account_verified=true and role=user.\nClient should call /login immediately after to get tokens.","operationId":"signup_verify_api_v1_user_signup_verify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupVerifyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupVerifyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/signup/resend-code":{"post":{"tags":["user"],"summary":"Resend email verification code","description":"Resend the email verification code via Cognito.","operationId":"resend_signup_code_api_v1_user_signup_resend_code_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendCodeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendCodeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/login":{"post":{"tags":["user"],"summary":"User login","description":"Authenticate via Cognito. Accepts email or Matrix username.","operationId":"login_api_v1_user_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/logout":{"post":{"tags":["user"],"summary":"User logout","description":"Logout: invalidate Cognito tokens and deactivate device tokens.","operationId":"logout_api_v1_user_logout_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LogoutRequest"},{"type":"null"}],"title":"Logout Data"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/user/token/refresh":{"post":{"tags":["user"],"summary":"Refresh access token","description":"Refresh an expired access token using a Cognito refresh token.\n\nReturns new access_token and id_token; the refresh_token itself does not rotate.","operationId":"refresh_token_api_v1_user_token_refresh_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/sessions":{"get":{"tags":["user"],"summary":"List active sessions","description":"Return all non-revoked sessions for the authenticated user.","operationId":"list_sessions_api_v1_user_sessions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionListResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/user/sessions/{session_id}":{"delete":{"tags":["user"],"summary":"Revoke a specific session","description":"Mark a session as revoked. Takes effect on the next token refresh attempt.","operationId":"revoke_session_api_v1_user_sessions__session_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"integer","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/email-availability":{"get":{"tags":["user"],"summary":"Check email availability","description":"Check if email is available for registration.","operationId":"check_email_availability_api_v1_user_email_availability_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAvailabilityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/phone-availability":{"get":{"tags":["user"],"summary":"Check phone number availability","description":"Check if a phone number is available for registration.","operationId":"check_phone_availability_api_v1_user_phone_availability_get","parameters":[{"name":"phone","in":"query","required":true,"schema":{"type":"string","title":"Phone"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneAvailabilityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/forgot-password":{"post":{"tags":["user"],"summary":"Initiate password reset","description":"Initiate password reset. Cognito sends a reset code to email.","operationId":"forgot_password_api_v1_user_forgot_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/reset-password":{"post":{"tags":["user"],"summary":"Reset password with OTP code","description":"Reset password using the code from forgot-password.","operationId":"reset_password_api_v1_user_reset_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/delete-account":{"post":{"tags":["user"],"summary":"Delete user account","description":"Delete account: verify password, soft-delete in DB, disable in Cognito, invalidate tokens.","operationId":"delete_account_api_v1_user_delete_account_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAccountRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAccountResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/user/self-deactivate":{"post":{"tags":["user"],"summary":"Self-deactivate account (post-Matrix UIAA)","description":"Verify the user's password and mark their account as deactivated in our DB,\nthen disable their Cognito login.\n\nCalled by the iOS app after a successful Matrix account/deactivate (UIAA)\ncall.  The password is re-verified here independently of Matrix UIAA so that\na session hijacker who has a valid token cannot silently delete the account.","operationId":"self_deactivate_api_v1_user_self_deactivate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelfDeactivateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/user/profile":{"get":{"tags":["user"],"summary":"Get current user's profile","description":"Get current authenticated user's profile.","operationId":"get_my_profile_api_v1_user_profile_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileOut"}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["user"],"summary":"Update user profile","description":"Update user profile (and create Matrix account on first registration).","operationId":"update_profile_api_v1_user_profile_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/user/username/check":{"get":{"tags":["user"],"summary":"Check username availability","description":"Check if a username is available.","operationId":"check_username_api_v1_user_username_check_get","parameters":[{"name":"candidate","in":"query","required":true,"schema":{"type":"string","minLength":5,"title":"Candidate"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameCheckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/{user_id}/recovery-key":{"post":{"tags":["user"],"summary":"Store recovery key","description":"Store recovery key from iOS app.","operationId":"store_recovery_key_api_v1_user__user_id__recovery_key_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreRecoveryKeyRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryKeyStoredResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["user"],"summary":"Get Recovery Key","description":"Get recovery key for user (decrypted).","operationId":"get_recovery_key_api_v1_user__user_id__recovery_key_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["user"],"summary":"Update recovery key","description":"Update existing recovery key.","operationId":"update_recovery_key_api_v1_user__user_id__recovery_key_put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRecoveryKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryKeyStoredResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["user"],"summary":"Delete recovery key","description":"Delete recovery key for user.","operationId":"delete_recovery_key_api_v1_user__user_id__recovery_key_delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryKeyStoredResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/{user_id}/recovery-key/exists":{"get":{"tags":["user"],"summary":"Check if recovery key exists","description":"Check if a recovery key exists for the user.","operationId":"check_recovery_key_exists_api_v1_user__user_id__recovery_key_exists_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryKeyExistsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/matrix-login":{"post":{"tags":["auth"],"summary":"Matrix client login","description":"Authenticate with the Matrix homeserver and receive an access token.","operationId":"matrix_login_api_v1_auth_matrix_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixLoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixLoginResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users":{"post":{"tags":["admin"],"summary":"Create a new user (admin)","description":"Create a user in Cognito, the local DB, **and** Synapse (Matrix).\n\nMatrix account needs a password at creation time, but Cognito's\nadmin_create_user with send_invite=True generates its own temp password\nwe can't read. We create Matrix with a random placeholder and set\n`needs_matrix_password_sync=True`; the next successful login picks up\nthe real password and syncs it to Matrix automatically (see user.py\nline 441). Admin can also use the Reset Password modal to set it now.\n\nIf no `username` is provided, we skip Matrix creation (we'd have no\nlocalpart to derive an MXID from). The Reset Password flow will still\nreport `user_has_no_matrix_id` until the admin edits the row to add\na username + re-runs this — TODO to make username required later.","operationId":"admin_create_user_api_v1_admin_users_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["admin"],"summary":"List all users (admin)","description":"Get a list of users in the database (Admin or Superadmin)","operationId":"list_all_users_api_v1_admin_users_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number","default":1,"title":"Page"},"description":"Page number"},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of results per page","default":100,"title":"Per Page"},"description":"Number of results per page"},{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","description":"Include deleted/deactivated users","default":true,"title":"Include Deleted"},"description":"Include deleted/deactivated users"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search by email, name, username, or display name","title":"Search"},"description":"Search by email, name, username, or display name"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}":{"patch":{"tags":["admin"],"summary":"Update a user's editable fields (admin)","description":"Update mutable user fields. Email and Matrix ID are not editable here.","operationId":"admin_update_user_api_v1_admin_users__user_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserUpdateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["admin"],"summary":"Get user by ID (admin)","description":"Get a specific user by ID (Admin only)","operationId":"get_user_api_v1_admin_users__user_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["admin"],"summary":"Hard-delete a user from everywhere (DB + Matrix + Cognito + Stripe + S3)","description":"Permanently and irreversibly remove a user from EVERY system that\nholds their identity, so the email / matrix_id / cognito sub / hardware\nfingerprint can be re-claimed for testing.\n\nRefuses to run when the target is itself an admin/superadmin (check the\n`admins` table by email) — demote first.\n\nRequires `?confirm_email=<exact-email>` to match the target's email.\nBelt-and-suspenders alongside the modal confirmation in adminweb so a\nmisclicked URL or scripted call can't nuke the wrong account.\n\nSteps (in order — earlier failures don't block later cleanup; final\nresponse reports per-system status):\n  1. Hard-delete each owned bot's Matrix account → frees `*_bot:` localparts.\n  2. Hard-delete each owned OpenClawInstance (cascades pair rows).\n  3. Wipe `openclaw_fingerprint_history` rows for this user_id —\n     operator-confirmed that for test-user wipe we want hardware\n     fingerprint amnesia (the user can re-trial on the same box).\n  4. Wipe `cli_access_tokens` + audit rows.\n  5. Wipe `bot_shares` (both as owner and recipient).\n  6. Cancel + delete the Stripe customer (if any).\n  7. Wipe S3 user uploads under `verifications/{user_id}/`.\n  8. Hard-delete the Matrix account → frees `@username:badger…`.\n  9. Cognito `admin_delete_user` by email → frees the email for re-signup.\n 10. Delete the `users` row → cascades any remaining child rows.\n\nReturns per-system status so the operator can see what landed.","operationId":"admin_hard_delete_user_api_v1_admin_users__user_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}},{"name":"confirm_email","in":"query","required":true,"schema":{"type":"string","title":"Confirm Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/stats":{"get":{"tags":["admin"],"summary":"Get admin statistics","description":"Get admin dashboard statistics (Admin only)","operationId":"get_admin_stats_api_v1_admin_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminStatsResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/usage":{"get":{"tags":["admin"],"summary":"Get platform-wide usage by period (admin)","description":"Return per-user resource usage for the given billing period.\nStorage is read from usage_summaries (DB); active bots are the live count.","operationId":"admin_get_usage_api_v1_admin_usage_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Billing period in YYYY-MM format (defaults to current month)","title":"Period"},"description":"Billing period in YYYY-MM format (defaults to current month)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/bots":{"get":{"tags":["admin"],"summary":"List all bots (admin)","operationId":"admin_list_bots_api_v1_admin_bots_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminBotsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/plans":{"get":{"tags":["admin"],"summary":"Admin List Plans","operationId":"admin_list_plans_api_v1_admin_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/openclaw/instances":{"get":{"tags":["admin"],"summary":"List all OpenClaw instances (admin)","description":"Return all registered OpenClaw instances with their owner and bots running on each.","operationId":"admin_openclaw_instances_api_v1_admin_openclaw_instances_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/openclaw/instances/{instance_id}":{"get":{"tags":["admin"],"summary":"Get OpenClaw instance detail (admin)","description":"Detail for a single OpenClaw instance: owner, heartbeat, and bots running on it.","operationId":"admin_openclaw_instance_detail_api_v1_admin_openclaw_instances__instance_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["admin"],"summary":"Delete an OpenClaw instance (admin)","description":"Hard-delete any OpenClaw instance regardless of owner. Admin-only.\n\nWhat gets removed:\n  - The `openclaw_instances` row.\n  - All `bot_instance_pairings` rows pointing at this instance (FK\n    ON DELETE CASCADE from the Phase D migration).\n  - All `openclaw_fingerprint_history` rows for this instance's\n    `machine_fingerprint`. Without this, a follow-up `badgerclaw\n    login` on the same hardware (any user, including the original\n    owner with a fresh account) hits `_check_trial_abuse` because\n    the fingerprint history rows for prior accounts on this machine\n    survive — locking the operator out of the very test reset this\n    endpoint is meant to enable. Reproduced 2026-04-30 on srv1554824:\n    admin deleted instance, fresh signup got 403 \"machine already\n    registered under another account\" with the trial-abuse message\n    masked by the CLI's pre-0.2.38 envelope-blind error parsing.\n\nTradeoff vs. prior policy: the audit trail no longer survives\ninstance deletion, so cross-user trial-abuse detection on the SAME\nhardware is reset every time an admin deletes any instance there.\nThis is intentional for an admin-only reset endpoint — operators\nusing it know they're creating a clean slate. If you need to keep\nthe audit trail and only delete the instance row, do it directly\nin psql; the API endpoint exists specifically for clean resets.\n\nWhat is preserved:\n  - The `bots` table — bot rows are unaffected. Their last pair-link\n    just disappears; pair them again to a different instance to keep\n    them running.\n\nUsed by ops/QA to reset test users back to a clean \"no machine\" state\nwithout their cooperation. Logs the action so it's traceable in\napplication logs.","operationId":"admin_delete_openclaw_instance_api_v1_admin_openclaw_instances__instance_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/bots/{bot_id}":{"get":{"tags":["admin"],"summary":"Get bot detail (admin)","description":"Detail for a single bot: owner, OpenClaw instance it's running on, rooms, runtime status.","operationId":"admin_bot_detail_api_v1_admin_bots__bot_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/bots/{bot_id}/migrate-runtime":{"post":{"tags":["admin"],"summary":"Soft-migrate a bot to a different runtime (admin)","description":"Flip `bots.runtime` so the next pair targets the new runtime.\n\n\"Soft\" migration: this endpoint changes the column only. The\noperator's CLI still has to re-pair the bot for the actual swap to\ntake effect (OC plugin's hold needs to drop, Hermes container needs\nto spin up). Until then the bot keeps running on the old runtime\nwith the new runtime label, which is fine because the per-bot\ncontainer/plugin lookup goes via `bots.runtime` at pair time.\n\nHard migration (transfer access token + device + recovery key\nin-place, zero re-pair) is a follow-up; the operator-side state\ntransfer is non-trivial and out of scope for this slice.\n\nValidation:\n  - target runtime is `openclaw` | `hermes`\n  - current runtime differs from target (no-op rejected)\n  - for `hermes` target: at least one of the owner's instances must\n    advertise `capabilities.hermes.installed == true`. Same gate\n    the iOS Phase 4 picker uses, so the admin-side button can't\n    mint an unsatisfiable migration.","operationId":"admin_migrate_bot_runtime_api_v1_admin_bots__bot_id__migrate_runtime_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrateRuntimeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/plans/{plan_id}":{"post":{"tags":["admin"],"summary":"Update subscription plan (admin)","operationId":"admin_update_plan_api_v1_admin_plans__plan_id__post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"plan_id","in":"path","required":true,"schema":{"type":"integer","title":"Plan Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPlanUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPlanUpdateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/subscription-addons":{"get":{"tags":["admin"],"summary":"List subscription addons (admin)","description":"Return every row in subscription_addons (active + inactive). Used by\nthe admin UI to show the current Stripe Price IDs and Apple product IDs\nfor the cloud VM addon (and any future addons).","operationId":"admin_list_subscription_addons_api_v1_admin_subscription_addons_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/subscription-addons/{addon_id}":{"patch":{"tags":["admin"],"summary":"Update a subscription addon (admin)","description":"Edit the addon's Price IDs, product IDs, price, or activation state.\n\nMirrors PATCH /admin/plans/{plan_id} — same field-allow-list pattern.\n``key`` is intentionally not editable: backend code looks rows up by\n``key`` (``core.subscription_addons.CLOUD_VM_ADDON_KEY``), so renaming\nwould orphan references.","operationId":"admin_update_subscription_addon_api_v1_admin_subscription_addons__addon_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"addon_id","in":"path","required":true,"schema":{"type":"integer","title":"Addon Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminSubscriptionAddonUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminSubscriptionAddonUpdateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/plan-features":{"post":{"tags":["admin"],"summary":"Upsert plan-feature mapping (admin)","operationId":"admin_upsert_plan_feature_api_v1_admin_plan_features_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPlanFeatureUpsertRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPlanFeatureUpsertResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/features":{"post":{"tags":["admin"],"summary":"Create a feature flag (admin)","operationId":"admin_create_feature_api_v1_admin_features_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminFeatureCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminFeatureCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/features/{feature_id}":{"delete":{"tags":["admin"],"summary":"Delete a feature flag (admin)","operationId":"admin_delete_feature_api_v1_admin_features__feature_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"feature_id","in":"path","required":true,"schema":{"type":"integer","title":"Feature Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminFeatureDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/refresh-capabilities":{"post":{"tags":["admin"],"summary":"Bust cached capabilities for a user (admin)","description":"Drop cached capabilities for a user so the next request re-reads the DB.\n\nCall this after directly editing `user_subscriptions` or `plan_features` in\nthe DB (otherwise the user stays on the old plan for up to the cache TTL).","operationId":"admin_refresh_user_capabilities_api_v1_admin_users__user_id__refresh_capabilities_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/deactivate":{"post":{"tags":["admin"],"summary":"Deactivate a user account (admin)","description":"Deactivate a user account: sets deletion_status, disables Cognito, creates audit log.","operationId":"admin_deactivate_user_api_v1_admin_users__user_id__deactivate_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserActionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/activate":{"post":{"tags":["admin"],"summary":"Reactivate a user account (admin)","description":"Reactivate a deactivated user account: clears deletion fields, enables Cognito.","operationId":"admin_activate_user_api_v1_admin_users__user_id__activate_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserActionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/matrix-deactivate":{"post":{"tags":["admin"],"summary":"Deactivate a user's Matrix account only (admin)","description":"Deactivate a user's Matrix account without touching their app account.","operationId":"admin_matrix_deactivate_user_api_v1_admin_users__user_id__matrix_deactivate_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserActionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/matrix-activate":{"post":{"tags":["admin"],"summary":"Activate a user's Matrix account only (admin)","description":"Re-activate a user's Matrix account without touching their app account.","operationId":"admin_matrix_activate_user_api_v1_admin_users__user_id__matrix_activate_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/matrix-recreate":{"post":{"tags":["admin"],"summary":"Re-activate an erased Matrix account (admin)","description":"Re-activate a Matrix account that was previously erased.\nAll prior message history remains erased permanently.","operationId":"admin_matrix_recreate_user_api_v1_admin_users__user_id__matrix_recreate_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/jobs/status":{"get":{"tags":["admin"],"summary":"Get background job scheduler status and recent runs (admin)","description":"Return APScheduler status and the last 10 matrix status job records.","operationId":"admin_jobs_status_api_v1_admin_jobs_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/jobs/matrix-status-refresh":{"post":{"tags":["admin"],"summary":"Manually trigger a Matrix status refresh for all users (admin)","description":"Queue a full Matrix account status refresh in the background.\n\nInserts a 'pending' job record synchronously before returning so that\nGET /admin/jobs/{job_id} is immediately resolvable.","operationId":"admin_trigger_matrix_refresh_api_v1_admin_jobs_matrix_status_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/jobs/{job_id}":{"get":{"tags":["admin"],"summary":"Get a single background job by ID (admin)","description":"Return live status for a single matrix_status_jobs record.","operationId":"admin_get_job_api_v1_admin_jobs__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/login":{"post":{"tags":["admin"],"summary":"Admin login","description":"Authenticate an admin account via Cognito and return tokens.","operationId":"admin_login_api_v1_admin_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminLoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminLoginResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/refresh":{"post":{"tags":["admin"],"summary":"Refresh admin access token","description":"Refresh an expired admin access token.","operationId":"admin_refresh_api_v1_admin_refresh_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminRefreshRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminRefreshResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/profile":{"get":{"tags":["admin"],"summary":"Get admin profile","description":"Get current admin's profile.","operationId":"admin_profile_api_v1_admin_profile_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProfileOut"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/logout":{"post":{"tags":["admin"],"summary":"Admin logout","description":"Logout admin — invalidate all Cognito tokens.","operationId":"admin_logout_api_v1_admin_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminLogoutResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/downgrade-requests":{"get":{"tags":["admin"],"summary":"List downgrade requests (admin)","description":"Paginated list of `downgrade_requests` rows with user email + plan info.\n\nFilters:\n  - `status=open|resolved|all` (default all)\n  - `reason=payment_failure|user_manual`","operationId":"admin_list_downgrade_requests_api_v1_admin_downgrade_requests_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","pattern":"^(all|open|resolved)$","default":"all","title":"Status"}},{"name":"reason","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(payment_failure|user_manual)$"},{"type":"null"}],"title":"Reason"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/over-capacity":{"get":{"tags":["admin"],"summary":"List users holding resources above their plan cap (admin)","description":"Users currently over-cap on any countable gate. One row per\n(user, feature) over-cap pair. Returns the linked `active_request_id`\nwhen the user has an unresolved downgrade_requests row.","operationId":"admin_over_capacity_report_api_v1_admin_over_capacity_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/supported-versions":{"get":{"tags":["admin"],"summary":"List admin-approved supported versions","description":"Return all supported_versions rows for the admin panel.","operationId":"admin_list_supported_versions_api_v1_admin_supported_versions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SupportedVersionOut"},"type":"array","title":"Response Admin List Supported Versions Api V1 Admin Supported Versions Get"}}}}},"security":[{"HTTPBearer":[]}]},"put":{"tags":["admin"],"summary":"Set the supported version for a component (admin)","description":"Upsert the supported version for cli / plugin / openclaw.","operationId":"admin_update_supported_version_api_v1_admin_supported_versions_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedVersionUpdateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedVersionUpdateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/compat-runs":{"post":{"tags":["admin"],"summary":"Webhook: receive a compat-suite run report","description":"Webhook posted by badgerclaw-openclaw-compat/run.sh after a smoke run.\n\nAuth: a shared secret in the `X-Compat-Webhook-Secret` header, compared\nagainst the `COMPAT_WEBHOOK_SECRET` env var. We deliberately don't require\nadmin JWT here — the harness runs from an engineer's local machine (or\nlater, an unattended runner), where mounting the admin auth flow is\noverkill. The secret is a single rotated string we share with whatever\nruns the harness.\n\nIdempotent on (openclaw_version, started_at): re-posting the same run\n(e.g. network retry) updates the existing row in place. The harness\nuses run-start time as its natural key.","operationId":"admin_compat_runs_webhook_api_v1_admin_compat_runs_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatRunIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatRunWebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["admin"],"summary":"List compat-suite runs (most recent first)","description":"List compat runs, optionally filtered by candidate version + runtime.\nNewest first. Used by the /supported-versions admin UI to populate the\nCompat column and the drilldown list. `runtime` defaults to all when\nomitted (back-compat); pass 'hermes' for the Hermes panel.","operationId":"admin_list_compat_runs_api_v1_admin_compat_runs_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"openclaw_version","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Openclaw Version"}},{"name":"runtime","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompatRunOut"},"title":"Response Admin List Compat Runs Api V1 Admin Compat Runs Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["admin"],"summary":"Delete every compat-suite run for an openclaw version","description":"Bulk-delete every run for a given openclaw_version. Useful for\nclearing an entire version's flake history in one click; the per-row\ndelete is the surgical alternative.","operationId":"admin_delete_compat_runs_for_version_api_v1_admin_compat_runs_delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"openclaw_version","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Openclaw Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatRunDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/compat-runs/dispatch":{"post":{"tags":["admin"],"summary":"Trigger a compat-suite run on GitHub Actions","description":"Trigger the openclaw compat workflow for a candidate version.\n\nHits GitHub's `workflow_dispatch` endpoint on the compat repo. The\nworkflow runs the harness and POSTs the report back to\n`/admin/compat-runs` (the webhook above), which the admin dashboard\nauto-renders.\n\nRequired env: `GITHUB_DISPATCH_TOKEN` — fine-grained PAT with\n`actions:write` on the repo that hosts the compat workflow.\n`GITHUB_DISPATCH_REPO` — `<owner>/<repo>`; defaults to\n`darkstaar4/badgerclaw-api` (the compat suite lives under\n`badgerclaw-openclaw-compat/` there since it was absorbed from the\nformer standalone repo).","operationId":"admin_dispatch_compat_run_api_v1_admin_compat_runs_dispatch_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/compat-runs/latest":{"get":{"tags":["admin"],"summary":"Get the latest compat-suite run for an openclaw version","description":"The single latest run for a given candidate version (+ optional\nruntime), or `null` if we've never tested it. The /supported-versions UI\ncalls this once per candidate row to render the Compat status column —\nthe Hermes row passes runtime='hermes' with the upstream tag.","operationId":"admin_latest_compat_run_api_v1_admin_compat_runs_latest_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"openclaw_version","in":"query","required":true,"schema":{"type":"string","title":"Openclaw Version"}},{"name":"runtime","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CompatRunOut"},{"type":"null"}],"title":"Response Admin Latest Compat Run Api V1 Admin Compat Runs Latest Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/compat-runs/{run_id}":{"delete":{"tags":["admin"],"summary":"Delete a single compat-suite run by id","description":"Permanently delete one compat run row. Used to clean up flake noise\nor accidental local-test posts from the /supported-versions admin UI.","operationId":"admin_delete_compat_run_api_v1_admin_compat_runs__run_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatRunDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/create-matrix-account":{"post":{"tags":["admin"],"summary":"Create a Synapse account for a user who doesn't have one yet","description":"Backfill path for users created before Matrix-creation was part of\nadmin_create_user. Uses a random placeholder password + sets\n`needs_matrix_password_sync=True` so the next successful login syncs\nthe real password (same mechanism as admin_create_user's Matrix step).\n\nRefuses if `user.matrix_id` is already set — use the Reset Password\nmodal instead to rotate an existing account's password.","operationId":"admin_create_matrix_account_api_v1_admin_users__user_id__create_matrix_account_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminCreateMatrixAccountRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminCreateMatrixAccountResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/reset-password":{"post":{"tags":["admin"],"summary":"Admin: override a user's BadgerClaw password (and sync Matrix)","description":"Force-set a user's password. Updates Cognito (iOS/BadgerClaw login) and,\nbest-effort, the matching Matrix account so Element/iOS Matrix sync\nkeeps working.\n\nMatrix sync is non-fatal — a failure there is reflected in\n`matrix_password_updated=false` in the response and the Cognito-side\nupdate still stands.","operationId":"admin_reset_user_password_api_v1_admin_users__user_id__reset_password_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResetPasswordRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResetPasswordResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/usage":{"get":{"tags":["admin"],"summary":"Per-user usage + plan limits for a billing period","description":"Mirror of `/me/usage` but admin-scoped to a specific user. Also surfaces\nthe 25 most recent usage_events for the period so admins can see what\nthe user actually did (chat media uploads, etc.) rather than only the\nrolled-up numbers.","operationId":"admin_get_user_usage_api_v1_admin_users__user_id__usage_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM, defaults to current month","title":"Period"},"description":"YYYY-MM, defaults to current month"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/instance-fingerprint-collisions":{"get":{"tags":["admin"],"summary":"List machine fingerprints that have been registered under multiple accounts (admin)","description":"Trial-abuse signal: surface machine_fingerprint values that appear in\nopenclaw_fingerprint_history under two or more distinct user_ids. The\nhistory table is append-only (it survives openclaw_instances row\ndeletion), so a churned account's fingerprint usage stays visible here\nlong after the original instance row is gone.\n\nRead-only signal — does not gate anything by itself. Block enforcement\nruns at /openclaw/register for users on the `free_trial` plan\n(`_check_trial_abuse` in routers/openclaw.py).","operationId":"admin_instance_fingerprint_collisions_api_v1_admin_instance_fingerprint_collisions_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/sessions":{"get":{"tags":["admin"],"summary":"List BadgerClaw API sessions for a user","operationId":"admin_list_user_sessions_api_v1_admin_users__user_id__sessions_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserSession"},"title":"Response Admin List User Sessions Api V1 Admin Users  User Id  Sessions Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/matrix-devices":{"get":{"tags":["admin"],"summary":"List Matrix devices for a user (proxies Synapse admin API)","operationId":"admin_list_user_matrix_devices_api_v1_admin_users__user_id__matrix_devices_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdminMatrixDevice"},"title":"Response Admin List User Matrix Devices Api V1 Admin Users  User Id  Matrix Devices Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/openclaw-instances":{"get":{"tags":["admin"],"summary":"List OpenClaw instances paired to a user","operationId":"admin_list_user_openclaw_instances_api_v1_admin_users__user_id__openclaw_instances_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdminOpenClawInstanceSummary"},"title":"Response Admin List User Openclaw Instances Api V1 Admin Users  User Id  Openclaw Instances Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/security":{"get":{"tags":["admin"],"summary":"Composite security view: sessions + Matrix devices + OpenClaw instances + flags","operationId":"admin_user_security_api_v1_admin_users__user_id__security_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserSecurityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/sign-out-all":{"post":{"tags":["admin"],"summary":"Sign the user out of every active session (BadgerClaw + Matrix + Cognito) — account stays active","operationId":"admin_sign_out_all_api_v1_admin_users__user_id__sign_out_all_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminSignOutAllResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/upload-url":{"get":{"tags":["upload"],"summary":"Get presigned S3 upload URL","description":"Generate a presigned PUT URL for uploading a verification document to S3.","operationId":"get_presigned_upload_url_api_v1_upload_url_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"filename","in":"query","required":true,"schema":{"type":"string","title":"Filename"}},{"name":"matrix_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional username localpart to use if profile not saved yet","title":"Matrix Id"},"description":"Optional username localpart to use if profile not saved yet"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadUrlResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/verification-document-url":{"post":{"tags":["upload","admin","upload"],"summary":"Get presigned GET URL for verification document (admin)","description":"Generate a presigned URL for accessing a verification document (Admin only).\nThe document_url should be a full S3 URL or a key path.","operationId":"get_verification_document_presigned_url_api_v1_admin_verification_document_url_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresignedUrlRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresignedUrlResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/upload/delete-presigned-url":{"post":{"tags":["upload"],"summary":"Get presigned S3 delete URL","operationId":"get_presigned_delete_url_api_v1_upload_delete_presigned_url_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFileRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePresignedUrlResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/notifications/history":{"get":{"tags":["notifications"],"summary":"Get notification history","description":"Get notification history for the current user","operationId":"get_notification_history_api_v1_notifications_history_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/notifications/test/{user_id}":{"post":{"tags":["notifications","admin","notifications"],"summary":"Send test notification to user (admin)","description":"Test notification system for a specific user (Admin only)","operationId":"test_notification_api_v1_admin_notifications_test__user_id__post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestNotificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/version/check":{"post":{"tags":["version"],"summary":"Check app version","description":"Called by mobile apps on startup to check if an update is required.","operationId":"check_app_version_api_v1_version_check_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionCheckRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionCheckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/version/latest/{platform}":{"get":{"tags":["version"],"summary":"Get latest version for platform","description":"Get the latest version information for a platform","operationId":"get_latest_version_api_v1_version_latest__platform__get","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string","title":"Platform"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/version/all":{"get":{"tags":["version"],"summary":"List all versions","description":"Get all versions (admin endpoint)","operationId":"get_all_versions_api_v1_version_all_get","parameters":[{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by platform","title":"Platform"},"description":"Filter by platform"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VersionResponse"},"title":"Response Get All Versions Api V1 Version All Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/version/create":{"post":{"tags":["version"],"summary":"Create app version (admin)","description":"Create a new app version (admin only)","operationId":"create_version_api_v1_version_create_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/version/{version_id}":{"put":{"tags":["version"],"summary":"Update app version (admin)","description":"Update an existing app version (admin only)","operationId":"update_version_api_v1_version__version_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"version_id","in":"path","required":true,"schema":{"type":"integer","title":"Version Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["version"],"summary":"Delete app version (admin)","description":"Delete an app version (admin only)","operationId":"delete_version_api_v1_version__version_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"version_id","in":"path","required":true,"schema":{"type":"integer","title":"Version Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/users":{"get":{"tags":["matrix"],"summary":"List Matrix homeserver users (admin)","description":"List Matrix users for an organization's homeserver\n\nRequires Superadmin role.","operationId":"list_matrix_users_api_v1_admin_matrix_users_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"from_user","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"From User"},"description":"Pagination offset"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of results","default":100,"title":"Limit"},"description":"Maximum number of results"},{"name":"guests","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Include guest users","title":"Guests"},"description":"Include guest users"},{"name":"deactivated","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Include deactivated users","title":"Deactivated"},"description":"Include deactivated users"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixUsersListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/users/{user_id}":{"get":{"tags":["matrix"],"summary":"Get Matrix user details (admin)","description":"Get Matrix user details\n\nRequires Superadmin role.","operationId":"get_matrix_user_api_v1_admin_matrix_users__user_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix user ID (e.g., '@username:domain.com')","title":"User Id"},"description":"Matrix user ID (e.g., '@username:domain.com')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixUserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/users/{user_id}/deactivate":{"post":{"tags":["matrix"],"summary":"Deactivate Matrix User","description":"Deactivate Matrix user\n\nRequires Superadmin role.\nNote: erase parameter is not directly supported by Matrix Admin API v2,\nbut user will be deactivated.","operationId":"deactivate_matrix_user_api_v1_admin_matrix_users__user_id__deactivate_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix user ID","title":"User Id"},"description":"Matrix user ID"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/MatrixDeactivateUserRequest"},{"type":"null"}],"title":"Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/users/{user_id}/reset-password":{"post":{"tags":["matrix"],"summary":"Reset Matrix User Password","description":"Reset Matrix user password\n\nRequires Superadmin role.\nNote: logout_devices parameter is not directly supported by Matrix Admin API v2,\nbut password reset will invalidate existing sessions.","operationId":"reset_matrix_user_password_api_v1_admin_matrix_users__user_id__reset_password_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix user ID","title":"User Id"},"description":"Matrix user ID"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixResetPasswordRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/rooms":{"get":{"tags":["matrix"],"summary":"List Matrix Rooms","description":"List Matrix rooms for an organization's homeserver\n\nRequires Superadmin role.\n\nSort direction accepts:\n- 'b', 'desc', 'descending' for descending order (backward)\n- 'f', 'asc', 'ascending' for ascending order (forward)","operationId":"list_matrix_rooms_api_v1_admin_matrix_rooms_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"from_room","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"From Room"},"description":"Pagination offset"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of results","default":100,"title":"Limit"},"description":"Maximum number of results"},{"name":"order_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Sort field","title":"Order By"},"description":"Sort field"},{"name":"dir","in":"query","required":false,"schema":{"type":"string","description":"Sort direction: 'b'/'desc' (backward/descending) or 'f'/'asc' (forward/ascending)","default":"b","title":"Dir"},"description":"Sort direction: 'b'/'desc' (backward/descending) or 'f'/'asc' (forward/ascending)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixRoomsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/rooms/meta":{"post":{"tags":["matrix"],"summary":"Batch-fetch room creation timestamps","description":"Resolve `m.room.create.origin_server_ts` for each requested room in\nparallel. Synapse's admin list/get room endpoints don't expose creation\ntime, so we pull state per room. Failures on individual rooms surface as\nnull entries — the whole batch shouldn't fail if one room 404s.","operationId":"matrix_rooms_meta_api_v1_admin_matrix_rooms_meta_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixRoomsMetaRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixRoomsMetaResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/matrix/rooms/{room_id}":{"get":{"tags":["matrix"],"summary":"Get Matrix Room","description":"Get Matrix room details\n\nRequires Superadmin role.","operationId":"get_matrix_room_api_v1_admin_matrix_rooms__room_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix room ID","title":"Room Id"},"description":"Matrix room ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixRoomResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["matrix"],"summary":"Delete Matrix Room","description":"Delete Matrix room\n\nRequires Superadmin role.","operationId":"delete_matrix_room_api_v1_admin_matrix_rooms__room_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix room ID","title":"Room Id"},"description":"Matrix room ID"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/MatrixDeleteRoomRequest"},{"type":"null"}],"title":"Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/rooms/{room_id}/members":{"get":{"tags":["matrix"],"summary":"Get Matrix Room Members","description":"Get Matrix room members\n\nRequires Superadmin role.","operationId":"get_matrix_room_members_api_v1_admin_matrix_rooms__room_id__members_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix room ID","title":"Room Id"},"description":"Matrix room ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixRoomMembersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/server/version":{"get":{"tags":["matrix"],"summary":"Get Matrix Server Version","description":"Get Matrix server version\n\nRequires Superadmin role.","operationId":"get_matrix_server_version_api_v1_admin_matrix_server_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixServerVersionResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/matrix/server/stats":{"get":{"tags":["matrix"],"summary":"Get Matrix Server Stats","description":"Get Matrix server statistics\n\nRequires Superadmin role.\nReturns aggregated statistics including media, users, and rooms.","operationId":"get_matrix_server_stats_api_v1_admin_matrix_server_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixServerStatsResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/matrix/test-endpoint":{"post":{"tags":["matrix"],"summary":"Test Matrix Endpoint","description":"Test arbitrary Matrix endpoint (for debugging)\n\nRequires Superadmin role.","operationId":"test_matrix_endpoint_api_v1_admin_matrix_test_endpoint_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixTestEndpointRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixTestEndpointResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/push/register":{"post":{"tags":["push"],"summary":"Register device for push notifications","description":"Register a device token for push notifications.\n\nSupports iOS and Android platforms:\n- iOS: environment='sandbox' → app_id='com.signout.appios.dev'\n- iOS: environment='production' → app_id='com.signout.appios'\n- Android: app_id='io.signout.android' (regardless of environment)","operationId":"register_push_device_api_v1_push_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDeviceRegistration"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDeviceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/push/environment":{"get":{"tags":["push"],"summary":"Get push notification environment","description":"Get the user's current push notification environment","operationId":"get_push_environment_api_v1_push_environment_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushEnvironmentResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/push/devices":{"get":{"tags":["push"],"summary":"List registered devices","description":"Get all registered devices for the current user","operationId":"get_user_devices_api_v1_push_devices_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/DeviceTokenInfo"},"type":"array","title":"Response Get User Devices Api V1 Push Devices Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/push/device/{device_id}":{"delete":{"tags":["push"],"summary":"Delete a device token","description":"Delete a specific device token","operationId":"delete_device_token_api_v1_push_device__device_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"device_id","in":"path","required":true,"schema":{"type":"integer","title":"Device Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/push/device/{device_id}/deactivate":{"put":{"tags":["push"],"summary":"Deactivate a device token","description":"Deactivate a device token without deleting it","operationId":"deactivate_device_token_api_v1_push_device__device_id__deactivate_put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"device_id","in":"path","required":true,"schema":{"type":"integer","title":"Device Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceDeactivateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/commands":{"get":{"tags":["bots"],"summary":"Get Bot Commands","description":"Return the slash-command catalog plus the registries iOS uses for\nper-room visibility filtering. Cached client-side once per app launch.","operationId":"get_bot_commands_api_v1_bots_commands_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotCommandsResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/bots":{"post":{"tags":["bots"],"summary":"Create a new bot","description":"Create a new bot for the current user.","operationId":"create_bot_api_v1_bots_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBotRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["bots"],"summary":"List bots owned by current user","description":"List all bots owned by the current user.\n\nReturns only active bots so the list matches the dashboard summary and the\nplan-limit check. Deleted/inactive bots are hidden from the app.\n\n`paired_to` is opt-in for back-compat: existing clients that don't pass\nit keep getting the full bot list (iOS Bot Management screen depends on\nthis — it shows every bot the user owns regardless of pairing).","operationId":"list_bots_api_v1_bots_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"paired_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"If provided, restricts the response to bots that have a `bot_instance_pairings` row pointing at this `instance_id`. Used by the plugin's account-audit so a multi-machine user's bots aren't recovered onto every machine on every audit tick.","title":"Paired To"},"description":"If provided, restricts the response to bots that have a `bot_instance_pairings` row pointing at this `instance_id`. Used by the plugin's account-audit so a multi-machine user's bots aren't recovered onto every machine on every audit tick."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BotResponse"},"title":"Response List Bots Api V1 Bots Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/username/check":{"get":{"tags":["bots"],"summary":"Check bot username availability","description":"Check if a bot username is available.","operationId":"check_bot_username_api_v1_bots_username_check_get","parameters":[{"name":"candidate","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":50,"title":"Candidate"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}":{"get":{"tags":["bots"],"summary":"Get bot details","description":"Get details of a specific bot (owner only).","operationId":"get_bot_api_v1_bots__bot_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["bots"],"summary":"Delete a bot","description":"Permanently delete a bot — removes from DB and deactivates the Matrix user (owner only).","operationId":"delete_bot_api_v1_bots__bot_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["bots"],"summary":"Update bot name","description":"Update bot name (owner only).","operationId":"update_bot_api_v1_bots__bot_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBotRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}/token":{"post":{"tags":["bots"],"summary":"Regenerate bot access token","description":"Regenerate access token for a bot (owner only). Previous token is immediately invalidated.","operationId":"regenerate_token_api_v1_bots__bot_id__token_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}/refresh-matrix-token":{"post":{"tags":["bots"],"summary":"Refresh a bot's Matrix access token (preserves device for E2EE)","description":"Get a fresh Matrix access token for a bot without destroying its E2EE device.\n\nCalled by the OpenClaw plugin when a token expires (M_UNKNOWN_TOKEN).\nUses the appservice login to create a new session on the same device_id.\n\nEmits structured log lines so operators can alert on token-refresh\nhealth (item 5E in `docs/Bot Token Resilience and Crash-Loop Hardening.md`):\n  - `event=bot_token_refresh_attempt` on every call (with outcome)\n  - `event=bot_token_revocation_detected` when Matrix returns 401 —\n    this is the smoking-gun signal from the 2026-04-29 outage and\n    should page on-call.","operationId":"refresh_matrix_token_api_v1_bots__bot_id__refresh_matrix_token_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshMatrixTokenRequest","default":{}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshMatrixTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}/rooms/{room_id}":{"post":{"tags":["bots"],"summary":"Add bot to a Matrix room","description":"Add a bot to a room (owner only).","operationId":"add_bot_to_room_api_v1_bots__bot_id__rooms__room_id__post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}},{"name":"room_id","in":"path","required":true,"schema":{"type":"string","title":"Room Id"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddBotToRoomRequest","default":{"mode":"auto"}}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotRoomResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["bots"],"summary":"Remove bot from a Matrix room","description":"Remove a bot from a room (owner only).","operationId":"remove_bot_from_room_api_v1_bots__bot_id__rooms__room_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}},{"name":"room_id","in":"path","required":true,"schema":{"type":"string","title":"Room Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotRoomRemoveResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}/rooms/{room_id}/mode":{"patch":{"tags":["bots"],"summary":"Update bot response mode in a room","description":"Toggle a bot between auto-reply and mention-only mode in a room.\n\n- 'auto': bot responds to every human message in the room\n- 'mention': bot only responds when @mentioned\n\nIn both modes, bots always ignore other bots' messages unless @mentioned.\nThis prevents echo loops in multi-bot rooms.","operationId":"update_bot_room_mode_api_v1_bots__bot_id__rooms__room_id__mode_patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}},{"name":"room_id","in":"path","required":true,"schema":{"type":"string","title":"Room Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBotRoomModeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotRoomResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}/rooms":{"get":{"tags":["bots"],"summary":"List rooms a bot is assigned to","description":"List all rooms a bot is assigned to (owner only).","operationId":"list_bot_rooms_api_v1_bots__bot_id__rooms_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BotRoomResponse"},"title":"Response List Bot Rooms Api V1 Bots  Bot Id  Rooms Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/rooms/{room_id}/cleanup":{"delete":{"tags":["bots"],"summary":"Cleanup room when all humans have left","description":"Called when a user leaves a room — if only bots remain, kick all bots and delete the room.","operationId":"cleanup_room_api_v1_bots_rooms__room_id__cleanup_delete","parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","title":"Room Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomCleanupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/cross-bot/send":{"post":{"tags":["bots"],"summary":"Cross Bot Send","description":"Send an @mention message from one bot to another.\n\nUsed for bot-to-bot communication: Bot A can ask Bot B a question\nby sending an @mention in a shared room. Bot B will see the mention\nand respond.\n\nThe sending bot must be owned by the authenticated user.","operationId":"cross_bot_send_api_v1_bots_cross_bot_send_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossBotMessageRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossBotMessageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/bots/cross-bot/group-chat":{"post":{"tags":["bots"],"summary":"Create Cross Bot Group Chat","description":"Create a group chat with the user + two bots for cross-bot conversation.\n\nFlow:\n1. Creates a new Matrix room with the human user and both bots\n2. Both bots auto-join (trusted_private_chat preset)\n3. Bot A sends an @mention message to Bot B with the question\n4. Returns the room ID so the caller can poll for Bot B's response\n\nThe human user sees the full conversation unfold in real-time.","operationId":"create_cross_bot_group_chat_api_v1_bots_cross_bot_group_chat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCrossBotGroupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCrossBotGroupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/bots/cross-bot/poll-response/{room_id}":{"get":{"tags":["bots"],"summary":"Poll Cross Bot Response","description":"Poll for a response from a target bot in a cross-bot group chat.\n\nReturns the first message from the target bot that was sent after `after_ts`.\nUsed by the initiating bot to detect when the target bot has responded.","operationId":"poll_cross_bot_response_api_v1_bots_cross_bot_poll_response__room_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","title":"Room Id"}},{"name":"target_bot_user_id","in":"query","required":true,"schema":{"type":"string","description":"Bot user ID to wait for response from","title":"Target Bot User Id"},"description":"Bot user ID to wait for response from"},{"name":"after_ts","in":"query","required":false,"schema":{"type":"integer","description":"Only return messages after this timestamp (ms)","default":0,"title":"After Ts"},"description":"Only return messages after this timestamp (ms)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/rooms/{room_id}/info":{"get":{"tags":["bots"],"summary":"Get Room Info","description":"Get room member info -- lists all members, separated into bots and humans.\n\nBots can use this to discover who else is in the room.","operationId":"get_room_info_api_v1_bots_rooms__room_id__info_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","title":"Room Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomInfoResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/rooms/{room_id}/messages":{"get":{"tags":["bots"],"summary":"Get Room Messages Endpoint","description":"Fetch recent messages from a room.\n\nUsed by bots to read responses from other bots after sending\na cross-bot @mention message. The bot can poll this endpoint\nto find the response from the target bot.","operationId":"get_room_messages_endpoint_api_v1_bots_rooms__room_id__messages_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","title":"Room Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}/shares":{"post":{"tags":["bot-shares"],"summary":"Share a bot with another user","description":"Create a share granting another user access to this bot (owner only).","operationId":"create_share_api_v1_bots__bot_id__shares_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShareRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["bot-shares"],"summary":"List active shares for a bot","description":"List all active (non-revoked, non-expired) shares for a bot (owner only).","operationId":"list_shares_api_v1_bots__bot_id__shares_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShareResponse"},"title":"Response List Shares Api V1 Bots  Bot Id  Shares Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}/shares/{share_id}":{"delete":{"tags":["bot-shares"],"summary":"Revoke a bot share","description":"Revoke a share (owner only). The recipient immediately loses access.","operationId":"revoke_share_api_v1_bots__bot_id__shares__share_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}},{"name":"share_id","in":"path","required":true,"schema":{"type":"integer","title":"Share Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bots/{bot_id}/sharing":{"patch":{"tags":["bot-shares"],"summary":"Toggle sharing on/off for a bot","description":"Enable or disable sharing for a bot. Disabling bulk-revokes all active shares (owner only).","operationId":"toggle_sharing_api_v1_bots__bot_id__sharing_patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharingToggleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/shared-bots":{"get":{"tags":["bot-shares"],"summary":"List bots shared with current user","description":"List all bots that have been shared with the current user.","operationId":"list_shared_bots_api_v1_me_shared_bots_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SharedBotResponse"},"type":"array","title":"Response List Shared Bots Api V1 Me Shared Bots Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me/shared-bots/{share_id}/leave":{"post":{"tags":["bot-shares"],"summary":"Leave a shared bot","description":"Recipient self-revokes a share — removes their own access to a shared bot.","operationId":"leave_shared_bot_api_v1_me_shared_bots__share_id__leave_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"integer","title":"Share Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/active-shares":{"get":{"tags":["bot-shares"],"summary":"List all active shares across all bots (for CLI sync)","description":"Returns every active share for all bots owned by current_user.\nAlso auto-expires any shares past their expires_at and queues\nexpiry notifications.","operationId":"list_active_shares_api_v1_me_active_shares_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveSharesResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/featured-rooms":{"get":{"tags":["featured-rooms"],"summary":"List featured public rooms (user-facing)","operationId":"list_featured_rooms_user_api_v1_featured_rooms_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedRoomUserListResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/featured-rooms/acknowledge":{"post":{"tags":["featured-rooms"],"summary":"Mark the iOS featured-rooms onboarding screen as seen","description":"Idempotent. iOS calls this after the auto-join screen is dismissed so\nthe user doesn't see it again on the next sign-in (or on a different\ndevice). Returns the persisted timestamp — the first call wins.","operationId":"acknowledge_featured_rooms_api_v1_featured_rooms_acknowledge_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedRoomAcknowledgeResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/featured-rooms":{"get":{"tags":["featured-rooms"],"summary":"List featured rooms with full admin metadata","operationId":"list_featured_rooms_admin_api_v1_admin_featured_rooms_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedRoomAdminListResponse"}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["featured-rooms"],"summary":"Add a public Matrix room to the featured list","operationId":"create_featured_room_api_v1_admin_featured_rooms_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedRoomCreateRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedRoomAdminItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/featured-rooms/{room_id}":{"patch":{"tags":["featured-rooms"],"summary":"Update featured-room curation fields and/or refresh metadata","operationId":"update_featured_room_api_v1_admin_featured_rooms__room_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix room ID","title":"Room Id"},"description":"Matrix room ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedRoomUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedRoomAdminItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["featured-rooms"],"summary":"Remove a room from the featured list","operationId":"delete_featured_room_api_v1_admin_featured_rooms__room_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix room ID","title":"Room Id"},"description":"Matrix room ID"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/matrix/rooms/{room_id}/feature":{"post":{"tags":["featured-rooms"],"summary":"Feature a Matrix room (alias for POST /admin/featured-rooms)","operationId":"feature_matrix_room_api_v1_admin_matrix_rooms__room_id__feature_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix room ID","title":"Room Id"},"description":"Matrix room ID"}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedRoomAdminItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["featured-rooms"],"summary":"Unfeature a Matrix room (alias for DELETE /admin/featured-rooms/{room_id})","operationId":"unfeature_matrix_room_api_v1_admin_matrix_rooms__room_id__feature_delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"room_id","in":"path","required":true,"schema":{"type":"string","description":"Matrix room ID","title":"Room Id"},"description":"Matrix room ID"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/pairing/create":{"post":{"tags":["pairing"],"summary":"Create a pairing code for a bot","description":"Generate a pairing code for a bot. Requires auth (bot owner).","operationId":"create_pairing_api_v1_pairing_create_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePairingRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePairingResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/pairing/redeem":{"post":{"tags":["pairing"],"summary":"Redeem a pairing code (OpenClaw plugin)","description":"No authentication required — called by the OpenClaw plugin to retrieve bot credentials.","operationId":"redeem_pairing_api_v1_pairing_redeem_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemPairingRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemPairingResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/pairing/sessions/{session_id}/repair":{"post":{"tags":["pairing"],"summary":"Trigger a repair for a degraded pairing session","description":"iOS Repair button handler. Creates a bot_refresh PendingCommand for\nthe CLI to pick up on its next heartbeat, and transitions the session\nto REPAIRING so the UI shows the in-progress state.","operationId":"repair_pairing_session_api_v1_pairing_sessions__session_id__repair_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepairResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/register":{"post":{"tags":["openclaw"],"summary":"Register or update an OpenClaw instance","description":"Register or update an OpenClaw instance for the current user.\n\nResolution order:\n  1. **Fingerprint mode** (`machine_fingerprint` provided) — primary.\n     Look up by `(owner_user_id == current_user, machine_fingerprint)`.\n     If matched → owner upsert. Survives CLI reinstall; not predictable\n     from outside, so squat-DoS via predicted instance_id can't lock\n     the user out (server mints a unique instance_id if the requested\n     one is taken).\n  2. **Lazy backfill** — if no fingerprint match but the user has an\n     existing row with the requested `instance_id` (legacy path),\n     populate the row's fingerprint and treat as owner upsert.\n  3. **Old-client fallback** — fingerprint not provided. Look up by\n     instance_id alone. Owner match → upsert. Cross-user → 403. New\n     row → cap check + create. This branch keeps current CLI/plugin\n     versions working unchanged.\n  4. **New instance** — cap check, trial-abuse check (free-trial users\n     can't register on a fingerprint already used by another account),\n     server-mint a unique instance_id if needed, create row, log to\n     fingerprint history.","operationId":"register_instance_api_v1_openclaw_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterInstanceRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstanceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/instances/{instance_id}":{"delete":{"tags":["openclaw"],"summary":"Delete an OpenClaw instance","description":"Delete the caller's owned OpenClaw instance.\n\nOwner-only operation under the strict 1:1 owner-to-instance model.\nNo collaborator branch — the collaborator concept was retired in PR\n#88 and the table itself dropped in this PR.","operationId":"delete_instance_api_v1_openclaw_instances__instance_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/status":{"get":{"tags":["openclaw"],"summary":"Get OpenClaw instance statuses","description":"Return all OpenClaw instances owned by the current user.\n\nStrict 1:1 owner-to-instance model. Collaborator rows are retired —\n`/openclaw/status` now mirrors what `/pairing/create` accepts, so the\niOS machine list and the pair button stay in sync. We deliberately keep\narchived / plan-disabled rows in the response so the client can show the\nuser's full machine footprint for cap purposes.\n\n`online` is derived from `MachineHeartbeat.is_online` when a heartbeat\nrow exists for the instance, falling back to the stored\n`OpenClawInstance.online` column for instances that have only ever\n`/openclaw/register`-ed and not yet heartbeated. The dashboard heartbeat\nhandler keeps both fields in sync going forward; this LEFT JOIN guards\nlegacy rows whose column drifted out of sync before the symmetric\nwrite landed.","operationId":"get_status_api_v1_openclaw_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/InstanceResponse"},"type":"array","title":"Response Get Status Api V1 Openclaw Status Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/cloud-vm":{"get":{"tags":["openclaw"],"summary":"List the user's cloud VMs","description":"Return only the user's cloud (Orgo) VMs, with the data the new VM\nManagement UI needs to render cards: name + provision_status + orgo ids\n+ entitlement link + bot count.\n\nDistinct from ``/dashboard/machines`` (which now scopes to local\ninstalls by default — cloud VMs are a separate product line as of the\nPhase 1 cap split). Owner-scoped.","operationId":"list_cloud_vms_api_v1_openclaw_cloud_vm_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["openclaw"],"summary":"Provision a cloud VM (Orgo) and bring it up as a Hermes host","description":"Provision a fresh Orgo VM in BadgerClaw's workspace, register an\nOpenClawInstance row for the user, and kick off the bring-up sequence\n(Node + CLI + ``setup --hermes`` + supervisord drop-in) as an in-process\nbackground task.\n\nReturns 202 with the instance_id + provision_status='booting'. Clients\npoll ``GET /openclaw/cloud-vm/{instance_id}/provision-status`` for\nprogress; final state is ``online`` or ``failed``.","operationId":"create_cloud_vm_api_v1_openclaw_cloud_vm_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCloudVmRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudVmResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/cloud-vm/{instance_id}/assign-to-addon":{"post":{"tags":["openclaw"],"summary":"Tie a cloud VM to a specific addon entitlement","description":"Link a cloud VM to a paid ``user_cloud_vm_addons`` row.\n\nUsed by the cancel-addon flow: when a user with multiple cloud VMs\ncancels one of their addons, the client asks them which VM should\nexpire with that addon. The picked VM gets ``vm_entitlement_id`` set\nto the addon row; the reconciler destroys it once the addon's\n``period_end`` passes.\n\nBody: ``{\"addon_id\": \"<uuid>\"}``. The addon must belong to the same\nuser; the VM must be an owned cloud VM. Re-assigning a VM that's\nalready linked is allowed (overwrites the link) — covers the case\nwhere the user changes their mind before the addon expires.\n\nTo clear the link (return the VM to 'included' or to no entitlement),\npass ``{\"addon_id\": null}``.","operationId":"assign_cloud_vm_to_addon_api_v1_openclaw_cloud_vm__instance_id__assign_to_addon_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Payload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/cloud-vm/{instance_id}/restart":{"post":{"tags":["openclaw"],"summary":"Restart a cloud VM","operationId":"restart_cloud_vm_api_v1_openclaw_cloud_vm__instance_id__restart_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/cloud-vm/{instance_id}":{"delete":{"tags":["openclaw"],"summary":"Destroy a cloud VM (stops billing)","description":"Terminate the Orgo VM AND drop the local OpenClawInstance row.\n\nA \"destroyed\" cloud VM should disappear from the user's dashboard — the\nrow exists purely to track a live machine, so leaving an offline tombstone\nbehind looks like a phantom machine you can still tap (with Restart and\nDestroy buttons that act on a non-existent VM). Also evict the heartbeat\nrow so dashboard/machines doesn't surface the same id from a stale\nMachineHeartbeat join.","operationId":"destroy_cloud_vm_api_v1_openclaw_cloud_vm__instance_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/cloud-vm/{instance_id}/provision-status":{"get":{"tags":["openclaw"],"summary":"Current bring-up status of a cloud VM","operationId":"cloud_vm_provision_status_api_v1_openclaw_cloud_vm__instance_id__provision_status_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/cloud-vm/in-flight":{"get":{"tags":["openclaw"],"summary":"List the user's cloud VMs that are mid-bring-up","description":"Return every cloud VM owned by the user whose bring-up has not yet\nsettled (``provision_status`` in ``booting``/``installing``/``setup``).\n\nLets a client that was killed during a long provision re-render the\nprogress banner on next launch without remembering which instance it\nwas polling. The empty list is the common case (no in-flight runs).","operationId":"cloud_vm_in_flight_api_v1_openclaw_cloud_vm_in_flight_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/InFlightCloudVMItem"},"type":"array","title":"Response Cloud Vm In Flight Api V1 Openclaw Cloud Vm In Flight Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/cloud-vm/addon":{"get":{"tags":["openclaw"],"summary":"List the user's cloud VM addons","description":"Return active / grace / cancelled addon rows for the current user.","operationId":"list_cloud_vm_addons_api_v1_openclaw_cloud_vm_addon_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/cloud-vm/addon/purchase":{"post":{"tags":["openclaw"],"summary":"Start Stripe Checkout for a cloud VM addon ($6/mo)","description":"Create a Stripe Checkout Session for one cloud VM addon.\n\nEach successful checkout produces a separate Stripe subscription whose\nonly line item is the addon Price; the corresponding ``user_cloud_vm_addons``\nrow is inserted by the ``customer.subscription.created`` webhook\nhandler in ``routers/subscription.py``.\n\nBody (all optional): ``{\"return_to\": \"app\" | \"web\"}`` — picks which\nsuccess/cancel URL pair Stripe redirects to after checkout. Mirrors\nthe same flag on ``POST /subscription/checkout``.\n\nCapability gate: ``cloud_vm_addon_eligible`` must be true (free users\nare blocked).","operationId":"purchase_cloud_vm_addon_api_v1_openclaw_cloud_vm_addon_purchase_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Payload","default":{}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/cloud-vm/addon/purchase-apple":{"post":{"tags":["openclaw"],"summary":"Verify Apple IAP receipt for a cloud VM addon and create the addon row","description":"Verify an Apple IAP receipt for the cloud VM addon SKU and record it.\n\nMirrors the Stripe ``/purchase`` endpoint above but for iOS: the iPhone\nclient buys the SKU via StoreKit, then POSTs the resulting receipt here\nso we can verify it server-side and create a ``user_cloud_vm_addons`` row\n(``source='apple'``, ``external_id=originalTransactionId``).\n\nBody: ``{\"receipt_data\": \"<base64>\", \"product_id\": \"com.badgerclaw.cloudvm.monthly\"}``.\n\nCapability gate: ``cloud_vm_addon_eligible`` must be true.\nOne-addon-per-iPhone gate (per §2 Apple multi-addon limit): rejects with\n409 if the user already has an active or grace Apple addon row.","operationId":"purchase_cloud_vm_addon_apple_api_v1_openclaw_cloud_vm_addon_purchase_apple_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/cloud-vm/addon/{addon_id}/cancel":{"post":{"tags":["openclaw"],"summary":"Cancel a cloud VM addon at period end","description":"Mark an addon for cancellation at its next renewal.\n\nPer the locked product policy: **no refunds, runs through the paid\nperiod, then the reconciler destroys the linked VM and unpairs its\nbots**. We do this by calling Stripe with ``cancel_at_period_end=true``\non the subscription; the resulting ``customer.subscription.updated``\nwebhook flips our local row to ``status='cancelled'`` with\n``period_end`` set, and ``jobs/cloud_vm_reconcile.py`` tears down at\nperiod_end.\n\nOwner-scoped. Stripe-only — Apple IAP cancel uses the iOS Settings\nflow instead — the iPhone re-validates the receipt on next app launch\nvia ``POST /openclaw/cloud-vm/addon/purchase-apple`` and the upsert\npicks up the cancel.","operationId":"cancel_cloud_vm_addon_api_v1_openclaw_cloud_vm_addon__addon_id__cancel_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"addon_id","in":"path","required":true,"schema":{"type":"string","title":"Addon Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/provision/bot":{"post":{"tags":["openclaw"],"summary":"Provision a new bot via OpenClaw","description":"Create a bot in the DB and send a Matrix provisioning event\nso an OpenClaw instance can pick it up.","operationId":"provision_bot_api_v1_openclaw_provision_bot_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionBotRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionBotResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/bots":{"get":{"tags":["openclaw"],"summary":"Cli List Bots","description":"List bots for the CLI (same data as /bots, CLI-friendly format).","operationId":"cli_list_bots_api_v1_openclaw_bots_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["openclaw"],"summary":"Cli Create Bot","description":"Create a bot from the CLI.","operationId":"cli_create_bot_api_v1_openclaw_bots_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Data"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/bots/{name}":{"delete":{"tags":["openclaw"],"summary":"Cli Delete Bot","description":"Deactivate a bot from the CLI (by username).","operationId":"cli_delete_bot_api_v1_openclaw_bots__name__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/cli/auth/start":{"post":{"tags":["openclaw"],"summary":"Start CLI PKCE authentication","description":"CLI calls this with a PKCE challenge.\nReturns a URL for the user to open in their browser.\nBody: { code_challenge: str, code_challenge_method: \"S256\" }","operationId":"cli_auth_start_api_v1_openclaw_cli_auth_start_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Data"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CliAuthStartResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/cli/auth/poll/{code}":{"post":{"tags":["openclaw"],"summary":"Cli Auth Poll","description":"CLI polls this until a token is available (user completed browser login).\nReturns: { status: \"pending\" } or { status: \"complete\", access_token, user_id }","operationId":"cli_auth_poll_api_v1_openclaw_cli_auth_poll__code__post","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"default":{},"title":"Data"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["openclaw"],"summary":"Cli Auth Poll","description":"CLI polls this until a token is available (user completed browser login).\nReturns: { status: \"pending\" } or { status: \"complete\", access_token, user_id }","operationId":"cli_auth_poll_api_v1_openclaw_cli_auth_poll__code__get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"default":{},"title":"Data"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/openclaw/cli/auth/callback":{"post":{"tags":["openclaw"],"summary":"Complete CLI authentication (web callback)","description":"Called by the web app after user logs in via browser.\nBody: { code: str, access_token: str }\nStores the token for the CLI to pick up via poll.\nSecurity: user is already authenticated via Bearer token (logged-in session).","operationId":"cli_auth_callback_api_v1_openclaw_cli_auth_callback_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Data"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CliAuthCallbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/pending-pairs":{"get":{"tags":["openclaw"],"summary":"Get unredeemed pairing codes","description":"Return unredeemed pair codes for the current user's bots. CLI polls this to auto-connect.","operationId":"get_pending_pairs_api_v1_openclaw_pending_pairs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/PendingPairResponse"},"type":"array","title":"Response Get Pending Pairs Api V1 Openclaw Pending Pairs Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/events":{"get":{"tags":["openclaw"],"summary":"SSE event stream for OpenClaw","description":"Server-Sent Events stream — returns bot provisioning, pairing, command execution, and Claude Code toggle events.","operationId":"sse_events_api_v1_openclaw_events_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/openclaw/pending-pairs/{code}/claim":{"post":{"tags":["openclaw"],"summary":"Claim a pending pairing code (CLI)","description":"CLI calls this after successfully auto-connecting a bot, so it won't be returned again.","operationId":"claim_pending_pair_api_v1_openclaw_pending_pairs__code__claim_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/hermes/bots/{bot_id}/logs":{"get":{"tags":["hermes"],"summary":"Tail logs from a Hermes bot's container (stub)","operationId":"get_hermes_logs_api_v1_hermes_bots__bot_id__logs_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}},{"name":"lines","in":"query","required":false,"schema":{"type":"integer","default":200,"title":"Lines"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HermesLogTailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/hermes/bots/{bot_id}/version":{"get":{"tags":["hermes"],"summary":"Report the running Hermes image + container id (stub)","operationId":"get_hermes_version_api_v1_hermes_bots__bot_id__version_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HermesVersionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/hermes/bots/{bot_id}/restart":{"post":{"tags":["hermes"],"summary":"Restart a Hermes bot's container (stub)","operationId":"restart_hermes_bot_api_v1_hermes_bots__bot_id__restart_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HermesRestartResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/hermes/bots/{bot_id}/runtime-bootstrap":{"post":{"tags":["hermes"],"summary":"Persist first-boot Hermes runtime state (cross-signing key, image)","description":"Called by the CLI immediately after it observes the cross-signing\nrecovery key in `docker logs`. Idempotent: the recovery key is\nfirst-write-wins (a Hermes bot bootstraps cross-signing exactly once\nper crypto store; re-bootstrap means the store was wiped, which is\nan error to flag separately). `image_ref` updates every call so\n`bots.runtime_version` always reflects what's actually running.\n\nAuth: owner JWT or CLI access token tied to the bot's owner.","operationId":"bootstrap_hermes_runtime_api_v1_hermes_bots__bot_id__runtime_bootstrap_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HermesRuntimeBootstrapRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HermesRuntimeBootstrapResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/subscription/pricing":{"get":{"tags":["subscription","subscription"],"summary":"Get public pricing plans","description":"Returns all active plans with features and prices. No authentication required.","operationId":"get_pricing_api_v1_subscription_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/subscription/plans":{"get":{"tags":["subscription","subscription"],"summary":"List active subscription plans","description":"Return all active subscription plans with their feature values.","operationId":"list_plans_api_v1_subscription_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/subscription":{"get":{"tags":["subscription"],"summary":"Get current subscription status","operationId":"get_subscription_api_v1_subscription_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionStatusResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/subscription/checkout":{"post":{"tags":["subscription"],"summary":"Create Stripe checkout session","operationId":"create_checkout_api_v1_subscription_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/subscription/portal":{"post":{"tags":["subscription"],"summary":"Create Stripe billing portal session","operationId":"create_portal_api_v1_subscription_portal_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/subscription/cancel":{"post":{"tags":["subscription"],"summary":"Cancel subscription at period end","operationId":"cancel_subscription_api_v1_subscription_cancel_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/subscription/change-plan":{"post":{"tags":["subscription"],"summary":"Change subscription plan (upgrade/downgrade)","operationId":"change_plan_api_v1_subscription_change_plan_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/subscription/payments":{"get":{"tags":["subscription"],"summary":"List the user's payment history (from local audit table)","description":"List payments from our local `payments` table (populated by webhooks).\n\nThis is our audit source of truth — faster than the Stripe API and survives\nStripe outages. If a customer has no rows yet (e.g. pre-existing user),\ncall `POST /subscription/payments/backfill` to seed from Stripe.","operationId":"list_payments_api_v1_subscription_payments_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/subscription/payments/backfill":{"post":{"tags":["subscription"],"summary":"Backfill the local payments audit table from Stripe (for the current user)","description":"One-shot: pull the user's historical invoices from Stripe into the local\n`payments` table. Safe to call repeatedly — upserts by invoice ID.","operationId":"backfill_payments_api_v1_subscription_payments_backfill_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/subscription/cancel-change":{"delete":{"tags":["subscription"],"summary":"Cancel pending plan change","operationId":"cancel_change_api_v1_subscription_cancel_change_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/subscription/apple/validate":{"post":{"tags":["subscription"],"summary":"Validate Apple IAP receipt","description":"Validate an Apple IAP receipt server-side.\n- Verifies with Apple's servers (production first, sandbox fallback)\n- Creates / updates UserSubscription row\n- Returns subscription status","operationId":"validate_apple_receipt_api_v1_subscription_apple_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppleReceiptRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppleReceiptResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/device-check/validate":{"post":{"tags":["trial"],"summary":"Validate Apple DeviceCheck token","description":"Validates the device to prevent trial abuse. Called during registration.","operationId":"validate_device_check_api_v1_device_check_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCheckRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCheckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/trial/status":{"get":{"tags":["trial"],"summary":"Get trial/subscription status","description":"Return current trial / subscription status for the authenticated user.\n\nLogic:\n1. If user has an active Stripe subscription → trial_active=True, has_active_subscription=True\n2. If within TRIAL_DURATION_DAYS of account creation → trial_active=True\n3. Otherwise → trial_active=False (trial expired, no subscription)","operationId":"get_trial_status_api_v1_trial_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialStatusResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/dashboard/heartbeat":{"post":{"tags":["dashboard"],"summary":"Submit CLI heartbeat","description":"Called by the OpenClaw CLI to report machine status and bot runtime stats.","operationId":"post_heartbeat_api_v1_dashboard_heartbeat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeartbeatPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeartbeatResponseV2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/dashboard/disconnect":{"post":{"tags":["dashboard"],"summary":"Mark a machine as offline immediately (graceful CLI shutdown)","description":"Flip the calling user's machine to offline without waiting for the\n75-second stale-heartbeat threshold in `jobs/dashboard_stale.py`.\n\nAuthoritative writes:\n  - `machine_heartbeats.is_online` → False\n  - `openclaw_instances.online`    → False (canonical row only)\n  - `bot_runtime_statuses.status`  → \"stopped\" for runtime rows on this\n    machine. Otherwise iOS would keep showing them as \"running\" until\n    the next stale-job tick.\n\nIdempotent: callable on every shutdown without side-effects on the next\nlegitimate heartbeat — that handler resurrects both fields the moment\n`gateway_status=\"running\"` is reported again.\n\nOwnership check: refuses unknown instance_ids and instances belonging\nto other users with 404 (mirrors the heartbeat endpoint's 410 guard,\nbut since the row may legitimately not exist for the user — e.g. a\nshutdown after admin instance-delete — 404 is the more honest code).","operationId":"post_disconnect_api_v1_dashboard_disconnect_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/dashboard/overview":{"get":{"tags":["dashboard"],"summary":"Get dashboard overview stats","description":"Aggregated dashboard stats for the authenticated user.","operationId":"get_overview_api_v1_dashboard_overview_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/dashboard/machines":{"get":{"tags":["dashboard"],"summary":"List all machines","description":"List the user's local machines.\n\nCloud VMs (``provider='orgo'``) are a separate product line as of the\nPhase 1 cap split and live on their own surface (``/openclaw/cloud-vm``)\n— they're excluded here by default so the bot dashboard isn't a mix of\nlocal installs and cloud rows. Old clients can opt in with\n``?include_cloud=1`` during the iOS 1.0.15 / macOS 0.1.19 transition.","operationId":"list_machines_api_v1_dashboard_machines_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"include_cloud","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Cloud"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachinesListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/dashboard/machines/{instance_id}":{"get":{"tags":["dashboard"],"summary":"Get machine detail","description":"Machine detail with full bot list and runtime statuses.","operationId":"get_machine_detail_api_v1_dashboard_machines__instance_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/dashboard/bots/{bot_id}/status":{"get":{"tags":["dashboard"],"summary":"Get bot runtime status","description":"Individual bot runtime detail with all telemetry fields.","operationId":"get_bot_status_api_v1_dashboard_bots__bot_id__status_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotRuntimeDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/dashboard/bots/{bot_id}/skills":{"get":{"tags":["dashboard"],"summary":"Get bot skills","description":"Return the skills list for a bot (from its most recent runtime status).","operationId":"get_bot_skills_api_v1_dashboard_bots__bot_id__skills_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SkillSummary"},"title":"Response Get Bot Skills Api V1 Dashboard Bots  Bot Id  Skills Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/dashboard/skills":{"get":{"tags":["dashboard"],"summary":"Get all skills across machines","description":"Aggregate skills from all user's machines, annotated with which machines have each skill.","operationId":"get_all_skills_api_v1_dashboard_skills_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SkillSummary"},"type":"array","title":"Response Get All Skills Api V1 Dashboard Skills Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/dashboard/skills/install":{"post":{"tags":["dashboard"],"summary":"Install a skill to a target machine","description":"Transfer a skill from one machine to another via pending command.\n\nFinds the skill content from any machine that has it, then sends an\ninstall_skill command to the target machine's CLI.","operationId":"install_skill_api_v1_dashboard_skills_install_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillInstallRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/dashboard/gateway/restart":{"post":{"tags":["dashboard"],"summary":"Restart CLI gateway","description":"Push a gateway-restart event via SSE to the target CLI instance.","operationId":"restart_gateway_api_v1_dashboard_gateway_restart_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayRestartRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayRestartResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/dashboard/commands":{"post":{"tags":["dashboard"],"summary":"Create a CLI command","description":"Create a remote update command for a CLI instance.","operationId":"create_command_api_v1_dashboard_commands_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommandRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/dashboard/commands/{instance_id}":{"get":{"tags":["dashboard"],"summary":"Get pending commands for an instance","description":"Get command statuses for an instance from the last 24 hours.","operationId":"get_command_statuses_api_v1_dashboard_commands__instance_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommandStatusResponse"},"title":"Response Get Command Statuses Api V1 Dashboard Commands  Instance Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/dashboard/commands/{command_id}/ack":{"post":{"tags":["dashboard"],"summary":"Acknowledge a command","description":"CLI acknowledges receipt of a command.","operationId":"ack_command_api_v1_dashboard_commands__command_id__ack_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"command_id","in":"path","required":true,"schema":{"type":"string","title":"Command Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/dashboard/commands/{command_id}/result":{"post":{"tags":["dashboard"],"summary":"Submit command result","description":"CLI reports the result of executing a command.","operationId":"report_command_result_api_v1_dashboard_commands__command_id__result_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"command_id","in":"path","required":true,"schema":{"type":"string","title":"Command Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandResultRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/dashboard/bots/{bot_id}/leave-room":{"post":{"tags":["dashboard"],"summary":"Command bot to leave a room","description":"Queue a leave-room command for the bot.","operationId":"leave_room_api_v1_dashboard_bots__bot_id__leave_room_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaveRoomRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/dashboard/versions/latest":{"get":{"tags":["dashboard"],"summary":"Get supported CLI/plugin/openclaw versions","description":"Return the admin-approved supported versions for Badger Hub + the CLI.\n\nShape consumed by Badger Hub / CLI / adminweb:\n  { cli, plugin, supported_openclaw, supported_hermes }\n\n`supported_hermes` is the upstream nousresearch/hermes-agent Docker tag\nthe CLI builds the BC image against (docker build --build-arg UPSTREAM=...).\n\nA value of \"unknown\" means the admin hasn't approved a version for that\ncomponent — consumers should treat that as \"do not offer an update\".\n\nThis endpoint is intentionally unauthenticated: it only reveals the\nadmin-approved version strings for three public npm packages, which is\nnot sensitive. Making it public also lets `badgerclaw setup` (run before\nthe user logs in) pin the plugin install to the approved version.","operationId":"get_latest_versions_api_v1_dashboard_versions_latest_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/dashboard/events":{"get":{"tags":["dashboard"],"summary":"Dashboard SSE event stream","description":"SSE endpoint for real-time dashboard updates.\niOS and landing connect here instead of polling.\n\nEvents pushed:\n- heartbeat.update: when a CLI sends a heartbeat (includes full overview)\n- bot.status.change: when a bot's status changes\n- machine.offline: when stale detection marks a machine offline\n- gateway.restart.requested: when a restart is triggered\n- gateway.restart.completed: when the CLI reports restart success","operationId":"dashboard_sse_events_api_v1_dashboard_events_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/capabilities":{"get":{"tags":["capabilities"],"summary":"Get user feature capabilities","description":"Returns a dynamic map of feature keys to their values for the authenticated user's current plan. Also includes live usage counters (bot_count, storage_mb_used) and active quota warnings.","operationId":"get_capabilities_api_v1_me_capabilities_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me/bot-dashboard":{"get":{"tags":["bot-dashboard"],"summary":"Get bot dashboard summary for current user","description":"Return aggregated Bot Dashboard stats for all active bots owned by the user.\nRequires Pro plan or above (bot_dashboard_access capability).","operationId":"get_bot_dashboard_summary_api_v1_me_bot_dashboard_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotDashboardSummary"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me/bot-dashboard/{bot_id}":{"get":{"tags":["bot-dashboard"],"summary":"Get detailed stats for a single bot","description":"Return detailed Bot Dashboard stats for a single bot.\nRequires Pro plan or above (bot_dashboard_access capability).","operationId":"get_bot_dashboard_detail_api_v1_me_bot_dashboard__bot_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"bot_id","in":"path","required":true,"schema":{"type":"string","title":"Bot Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotDashboardBotStats"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/usage":{"get":{"tags":["usage"],"summary":"Get current usage vs plan limits","description":"Returns metered resource usage for the current billing period alongside plan limits.","operationId":"get_usage_api_v1_me_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me/usage/track-media":{"post":{"tags":["usage"],"summary":"Record a chat media upload","description":"Called by the iOS app after each successful Synapse media upload. Checks the storage_mb plan limit before recording; returns 403 if the upload would exceed it.","operationId":"track_media_upload_api_v1_me_usage_track_media_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackMediaRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/support/report":{"post":{"tags":["support"],"summary":"Submit a bug report","operationId":"submit_bug_report_api_v1_support_report_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BugReportRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/admin/support/reports":{"get":{"tags":["support"],"summary":"List bug reports (admin only)","description":"Returns bug reports sorted by priority (priority_support first),\nthen newest first within each tier. Optional status / user filters.","operationId":"list_bug_reports_api_v1_admin_support_reports_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status","title":"Status"},"description":"Filter by status"},{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter to tickets from one user","title":"User Id"},"description":"Filter to tickets from one user"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/support/reports/{report_id}":{"get":{"tags":["support"],"summary":"Fetch a single bug report (admin only)","operationId":"get_bug_report_api_v1_admin_support_reports__report_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["support"],"summary":"Update a bug report (admin only)","operationId":"update_bug_report_api_v1_admin_support_reports__report_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","title":"Report Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBugReportRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["support"],"summary":"Delete a bug report (admin only)","operationId":"delete_bug_report_api_v1_admin_support_reports__report_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/support/reports/{report_id}/resolve":{"post":{"tags":["support"],"summary":"Mark a bug report resolved (admin only)","operationId":"resolve_bug_report_api_v1_admin_support_reports__report_id__resolve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/subscription/downgrade":{"post":{"tags":["downgrade"],"summary":"Manually initiate a plan downgrade","operationId":"manual_downgrade_api_v1_me_subscription_downgrade_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualDowngradeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ActiveDowngradeResponse"},{"type":"null"}],"title":"Response Manual Downgrade Api V1 Me Subscription Downgrade Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me/downgrade-requests/active":{"get":{"tags":["downgrade"],"summary":"Get the current user's unresolved downgrade request, if any","operationId":"get_active_api_v1_me_downgrade_requests_active_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ActiveDowngradeResponse"},{"type":"null"}],"title":"Response Get Active Api V1 Me Downgrade Requests Active Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me/downgrade-requests/{request_id}/resolve":{"post":{"tags":["downgrade"],"summary":"Submit the keep-set for one pick-N feature of a downgrade request","description":"Per-feature resolve. Caller supplies which gate they're resolving +\nthe keep-set for that gate. The request is marked `resolved_at` only\nwhen every gate that's currently over-cap has been resolved.","operationId":"resolve_downgrade_api_v1_me_downgrade_requests__request_id__resolve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveDowngradeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveDowngradeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/downgrade-preview":{"get":{"tags":["downgrade"],"summary":"Admin — preview the user's downgrade picker (read-only)","description":"Returns the same shape the user's own `/me/downgrade-requests/active`\nreturns — request metadata plus every over-cap feature and the exact\nitems (bots, instances, shares) the user would pick from.\n\nRead-only. Admin cannot resolve on the user's behalf; the resolve\nendpoint stays `/me/downgrade-requests/{id}/resolve` (user-only).\nReturns `null` when the user has no unresolved request.","operationId":"admin_downgrade_preview_api_v1_admin_users__user_id__downgrade_preview_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ActiveDowngradeResponse"},{"type":"null"}],"title":"Response Admin Downgrade Preview Api V1 Admin Users  User Id  Downgrade Preview Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/subscription/downgrade":{"post":{"tags":["downgrade"],"summary":"Admin — initiate a plan downgrade on behalf of a user","description":"Open a downgrade_requests row for `user_id` with reason='admin_manual'.\n\nIdempotent — returns the existing unresolved request if one is already\nopen (matching the user-facing manual_downgrade behavior). When the\nuser is already within every pick-N cap on the target plan, no row is\nopened and the endpoint returns `null` (force_immediate still flips\ncaps to the target plan as a side effect).\n\nStripe is not touched here; the downgrade request is purely a\nBadgerClaw-side state change. Sync with Stripe separately.","operationId":"admin_initiate_downgrade_api_v1_admin_users__user_id__subscription_downgrade_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminManualDowngradeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ActiveDowngradeResponse"},{"type":"null"}],"title":"Response Admin Initiate Downgrade Api V1 Admin Users  User Id  Subscription Downgrade Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/downgrade-requests/{request_id}/resolve":{"post":{"tags":["downgrade"],"summary":"Admin — resolve one pick-N feature of a user's downgrade request","description":"Per-feature resolve on behalf of a user. Mirrors the user's own\n/me/downgrade-requests/{id}/resolve. The admin picks which resources\nthe user keeps; everything unselected gets disabled. Records\nresolved_by_admin_id and sets resolution='admin_resolved' once every\nover-cap gate is resolved.","operationId":"admin_resolve_downgrade_api_v1_admin_users__user_id__downgrade_requests__request_id__resolve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}},{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveDowngradeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveDowngradeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/downgrade-requests/{request_id}":{"delete":{"tags":["downgrade"],"summary":"Admin — cancel an in-flight downgrade and revert side-effects","description":"Hard-cancel a downgrade_requests row (resolved or not). Reverts the\nobvious BadgerClaw-side side-effects:\n\n  - `user_subscriptions.source='admin_override'` rows inserted by\n    `create_downgrade_request` with `force_immediate=true` are\n    removed (the capability-flip undone).\n  - `user_subscriptions` rows flipped to `canceled` / `grace` by the\n    same call are restored to `active` and `grace_until` cleared.\n  - Every Bot with `plan_disabled_at IS NOT NULL` owned by the user\n    has the flag cleared; the Matrix account is reactivated so the\n    bot can send/receive again.\n  - Every OpenClawInstance with `plan_disabled_at IS NOT NULL`\n    owned by the user is re-enabled.\n  - Per-user capability cache is busted.\n\nStripe is not touched — the original `create_downgrade_request`\ncontract is \"BadgerClaw-side only; admin reconciles Stripe\nseparately\". Cancel keeps the same invariant: if\n`user.subscription_price_id` was rewritten by force_immediate, it\nis left in place because we don't have a durable record of what it\nwas before. Admin can fix manually via the user edit form if\nneeded (common case: it already points at the correct Stripe\nprice).","operationId":"admin_cancel_downgrade_api_v1_admin_users__user_id__downgrade_requests__request_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}},{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/subscription/upgrade":{"post":{"tags":["downgrade"],"summary":"Admin — bump a user's plan up to a higher tier","description":"Raise `user_id`'s BadgerClaw-side plan to `data.to_plan` immediately.\n\nNo Stripe interaction — same invariant as the downgrade endpoint\n(admin reconciles Stripe separately). The user is NOT asked for\npayment; the admin takes responsibility for billing-side alignment.\n\nBehaviour:\n  - Validates `to_plan` is a strictly higher tier than the user's\n    current plan.\n  - Inserts a new user_subscriptions row with\n    `source='admin_override'`, `status='active'`, `plan_id=target`.\n    `_active_plan_id` picks the newest active row, so capability\n    resolution flips up immediately.\n  - Updates `users.subscription_price_id` to the target plan's\n    Stripe price id (sandbox column chosen by STRIPE_IS_SANDBOX)\n    so `/me/subscription`'s plan-name resolver matches.\n  - If the user has an unresolved DowngradeRequest, this is the\n    re-upgrade path: `try_resolve_as_reupgrade` clears\n    plan_disabled_at on bots + reactivates Matrix + closes the\n    request with resolution='re_upgraded'.\n  - Invalidates the per-user capability cache.","operationId":"admin_initiate_upgrade_api_v1_admin_users__user_id__subscription_upgrade_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"integer","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminManualUpgradeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/upgrade-requests/active":{"get":{"tags":["upgrade"],"summary":"Get the current user's unresolved upgrade request, if any","operationId":"get_active_api_v1_me_upgrade_requests_active_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ActiveUpgradeResponse"},{"type":"null"}],"title":"Response Get Active Api V1 Me Upgrade Requests Active Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me/upgrade-requests/{request_id}/resolve":{"post":{"tags":["upgrade"],"summary":"Commit a reenable-set for one feature","operationId":"resolve_api_v1_me_upgrade_requests__request_id__resolve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveUpgradeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveUpgradeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/upgrade-requests/{request_id}/dismiss":{"post":{"tags":["upgrade"],"summary":"Close the upgrade wizard without reactivating anything","operationId":"dismiss_api_v1_me_upgrade_requests__request_id__dismiss_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/assistant/chat":{"post":{"tags":["assistant"],"summary":"Proxy chat to AI assistant","description":"Relay chat messages to DeepSeek API. Rate limited to prevent abuse.","operationId":"assistant_chat_api_v1_assistant_chat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/user/cli-tokens":{"post":{"tags":["cli-access-tokens"],"summary":"Mint a new CLI access token","operationId":"mint_token_api_v1_user_cli_tokens_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintTokenRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["cli-access-tokens"],"summary":"List the authenticated user's CLI access tokens","operationId":"list_tokens_api_v1_user_cli_tokens_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"If true, only return non-revoked tokens. Default: all.","title":"Active"},"description":"If true, only return non-revoked tokens. Default: all."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TokenListItem"},"title":"Response List Tokens Api V1 User Cli Tokens Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/cli-tokens/{token_id}":{"get":{"tags":["cli-access-tokens"],"summary":"Introspect a single CLI access token (metadata + recent audit)","operationId":"introspect_token_api_v1_user_cli_tokens__token_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenIntrospectResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["cli-access-tokens"],"summary":"Revoke a CLI access token","operationId":"revoke_token_api_v1_user_cli_tokens__token_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}},{"name":"cascade","in":"query","required":false,"schema":{"type":"boolean","description":"If true, also disconnect every openclaw_instances row paired via this token. Defaults to false — existing sessions survive.","default":false,"title":"Cascade"},"description":"If true, also disconnect every openclaw_instances row paired via this token. Defaults to false — existing sessions survive."}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/cli-tokens/{token_id}/unbind":{"post":{"tags":["cli-access-tokens"],"summary":"Clear the instance binding on a token so it can re-bind on next use","operationId":"unbind_token_api_v1_user_cli_tokens__token_id__unbind_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnbindTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/user/cli-tokens/{token_id}/rotate":{"post":{"tags":["cli-access-tokens"],"summary":"Rotate a token: mint a replacement and revoke the old one atomically","operationId":"rotate_token_api_v1_user_cli_tokens__token_id__rotate_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/RotateTokenRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ActiveDowngradeResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"from_plan":{"type":"string","title":"From Plan"},"to_plan":{"type":"string","title":"To Plan"},"reason":{"type":"string","title":"Reason"},"initiated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Initiated At"},"grace_ended_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Grace Ended At"},"features":{"items":{"$ref":"#/components/schemas/FeatureDowngradeState"},"type":"array","title":"Features"},"feature":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit"},"current_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current Count"},"items":{"items":{"$ref":"#/components/schemas/DowngradeItem"},"type":"array","title":"Items"}},"type":"object","required":["request_id","from_plan","to_plan","reason","initiated_at","grace_ended_at","features"],"title":"ActiveDowngradeResponse"},"ActiveShareItem":{"properties":{"share_id":{"type":"integer","title":"Share Id"},"bot_id":{"type":"string","title":"Bot Id"},"bot_user_id":{"type":"string","title":"Bot User Id"},"shared_with_user_id":{"type":"string","title":"Shared With User Id"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["share_id","bot_id","bot_user_id","shared_with_user_id"],"title":"ActiveShareItem"},"ActiveSharesResponse":{"properties":{"shares":{"items":{"$ref":"#/components/schemas/ActiveShareItem"},"type":"array","title":"Shares"}},"type":"object","required":["shares"],"title":"ActiveSharesResponse"},"ActiveUpgradeResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"from_plan":{"type":"string","title":"From Plan"},"to_plan":{"type":"string","title":"To Plan"},"trigger":{"type":"string","title":"Trigger"},"initiated_at":{"type":"string","format":"date-time","title":"Initiated At"},"features":{"items":{"$ref":"#/components/schemas/UpgradeFeatureState"},"type":"array","title":"Features"}},"type":"object","required":["request_id","from_plan","to_plan","trigger","initiated_at","features"],"title":"ActiveUpgradeResponse"},"AddBotToRoomRequest":{"properties":{"mode":{"type":"string","pattern":"^(auto|mention)$","title":"Mode","description":"Response mode: 'auto' (reply to all) or 'mention' (reply only when @mentioned)","default":"auto"}},"type":"object","title":"AddBotToRoomRequest"},"AdminBotsListResponse":{"properties":{"bots":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Bots"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["bots","total","page","limit"],"title":"AdminBotsListResponse"},"AdminCreateMatrixAccountRequest":{"properties":{"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"}},"type":"object","title":"AdminCreateMatrixAccountRequest"},"AdminCreateMatrixAccountResponse":{"properties":{"matrix_id":{"type":"string","title":"Matrix Id"},"matrix_account_created":{"type":"boolean","title":"Matrix Account Created"},"matrix_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Error"}},"type":"object","required":["matrix_id","matrix_account_created"],"title":"AdminCreateMatrixAccountResponse"},"AdminFeatureCreateRequest":{"properties":{"key":{"type":"string","title":"Key","description":"Unique feature key","example":"ai_generation"},"name":{"type":"string","title":"Name","description":"Human-readable feature name"},"feature_type":{"type":"string","title":"Feature Type","description":"Feature value type: boolean | limit | tier","example":"boolean"},"default_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Value","description":"Default value when not on a plan"}},"type":"object","required":["key","name","feature_type"],"title":"AdminFeatureCreateRequest"},"AdminFeatureCreateResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"feature":{"additionalProperties":true,"type":"object","title":"Feature"}},"type":"object","required":["ok","feature"],"title":"AdminFeatureCreateResponse"},"AdminFeatureDeleteResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"}},"type":"object","required":["ok"],"title":"AdminFeatureDeleteResponse"},"AdminLoginRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Admin email address"},"password":{"type":"string","minLength":1,"title":"Password","description":"Admin password"}},"type":"object","required":["email","password"],"title":"AdminLoginRequest"},"AdminLoginResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"access_token":{"type":"string","title":"Access Token"},"id_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id Token"},"refresh_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refresh Token"},"expires_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires In"},"token_type":{"type":"string","title":"Token Type","default":"Bearer"},"admin_profile":{"$ref":"#/components/schemas/AdminProfileOut"}},"type":"object","required":["success","access_token","admin_profile"],"title":"AdminLoginResponse"},"AdminLogoutResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"AdminLogoutResponse"},"AdminManualDowngradeRequest":{"properties":{"to_plan":{"type":"string","title":"To Plan","description":"Name of the plan to downgrade the user to."},"force_immediate":{"type":"boolean","title":"Force Immediate","description":"Skip the 7-day grace window; mark grace as already ended and drop the user's subscription straight to canceled. Default false.","default":false}},"type":"object","required":["to_plan"],"title":"AdminManualDowngradeRequest"},"AdminManualUpgradeRequest":{"properties":{"to_plan":{"type":"string","title":"To Plan","description":"Name of the plan to upgrade the user to — must be a higher tier than the current plan."}},"type":"object","required":["to_plan"],"title":"AdminManualUpgradeRequest"},"AdminMatrixDevice":{"properties":{"device_id":{"type":"string","title":"Device Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"last_seen_user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen User Agent"},"last_seen_ip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen Ip"},"last_seen_ts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Seen Ts"}},"type":"object","required":["device_id"],"title":"AdminMatrixDevice"},"AdminOpenClawInstanceSummary":{"properties":{"id":{"type":"string","title":"Id"},"instance_id":{"type":"string","title":"Instance Id"},"label":{"type":"string","title":"Label"},"version":{"type":"string","title":"Version"},"online":{"type":"boolean","title":"Online"},"last_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Seen"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"archived_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Archived At"},"machine_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Machine Fingerprint"}},"type":"object","required":["id","instance_id","label","version","online"],"title":"AdminOpenClawInstanceSummary"},"AdminPlanFeatureUpsertRequest":{"properties":{"plan_id":{"type":"integer","title":"Plan Id"},"feature_id":{"type":"integer","title":"Feature Id"},"value":{"type":"string","title":"Value","description":"Feature value (e.g. \"true\", \"1000\", \"high\")"},"display_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Label","description":"Display label shown on the public pricing page"}},"type":"object","required":["plan_id","feature_id","value"],"title":"AdminPlanFeatureUpsertRequest"},"AdminPlanFeatureUpsertResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"plan_feature":{"additionalProperties":true,"type":"object","title":"Plan Feature"}},"type":"object","required":["ok","plan_feature"],"title":"AdminPlanFeatureUpsertResponse"},"AdminPlanUpdateRequest":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"web_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Web Price"},"monthly_web_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Web Price"},"yearly_web_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Yearly Web Price"},"ios_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ios Price"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"},"stripe_price_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id"},"stripe_price_id_yearly":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id Yearly"},"stripe_price_id_sandbox":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id Sandbox"},"stripe_price_id_yearly_sandbox":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id Yearly Sandbox"}},"type":"object","title":"AdminPlanUpdateRequest"},"AdminPlanUpdateResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"plan":{"additionalProperties":true,"type":"object","title":"Plan"}},"type":"object","required":["ok","plan"],"title":"AdminPlanUpdateResponse"},"AdminProfileOut":{"properties":{"id":{"type":"integer","title":"Id"},"email":{"type":"string","title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"type":"string","title":"Role"},"is_active":{"type":"boolean","title":"Is Active"},"last_login_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Login At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","email","role","is_active"],"title":"AdminProfileOut"},"AdminRecentActivity":{"properties":{"signups_last_7_days":{"type":"integer","title":"Signups Last 7 Days"},"logins_last_7_days":{"type":"integer","title":"Logins Last 7 Days"}},"type":"object","required":["signups_last_7_days","logins_last_7_days"],"title":"AdminRecentActivity"},"AdminRefreshRequest":{"properties":{"refresh_token":{"type":"string","title":"Refresh Token"},"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["refresh_token","email"],"title":"AdminRefreshRequest"},"AdminRefreshResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"access_token":{"type":"string","title":"Access Token"},"id_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id Token"},"expires_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires In"},"token_type":{"type":"string","title":"Token Type","default":"Bearer"}},"type":"object","required":["success","access_token"],"title":"AdminRefreshResponse"},"AdminResetPasswordRequest":{"properties":{"new_password":{"type":"string","title":"New Password"}},"type":"object","required":["new_password"],"title":"AdminResetPasswordRequest"},"AdminResetPasswordResponse":{"properties":{"password_reset_at":{"type":"string","title":"Password Reset At"},"matrix_password_updated":{"type":"boolean","title":"Matrix Password Updated"},"matrix_sync_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Sync Reason"}},"type":"object","required":["password_reset_at","matrix_password_updated"],"title":"AdminResetPasswordResponse"},"AdminSignOutAllResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"user_id":{"type":"integer","title":"User Id"},"sessions_revoked":{"type":"integer","title":"Sessions Revoked"},"matrix_devices_total":{"type":"integer","title":"Matrix Devices Total"},"matrix_devices_deleted":{"type":"integer","title":"Matrix Devices Deleted"},"matrix_devices_failed":{"type":"integer","title":"Matrix Devices Failed"},"cognito_global_sign_out":{"type":"boolean","title":"Cognito Global Sign Out"},"cognito_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cognito Error"},"matrix_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Error"}},"type":"object","required":["ok","user_id","sessions_revoked","matrix_devices_total","matrix_devices_deleted","matrix_devices_failed","cognito_global_sign_out"],"title":"AdminSignOutAllResponse"},"AdminStatsResponse":{"properties":{"total_users":{"type":"integer","title":"Total Users"},"verified_users":{"type":"integer","title":"Verified Users"},"unverified_users":{"type":"integer","title":"Unverified Users"},"deleted_users":{"type":"integer","title":"Deleted Users"},"recent_activity":{"$ref":"#/components/schemas/AdminRecentActivity"}},"type":"object","required":["total_users","verified_users","unverified_users","deleted_users","recent_activity"],"title":"AdminStatsResponse"},"AdminSubscriptionAddonUpdateRequest":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"monthly_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Price"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"},"stripe_price_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id"},"stripe_price_id_yearly":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id Yearly"},"stripe_price_id_sandbox":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id Sandbox"},"stripe_price_id_yearly_sandbox":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id Yearly Sandbox"},"apple_product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Apple Product Id"},"apple_product_id_yearly":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Apple Product Id Yearly"}},"type":"object","title":"AdminSubscriptionAddonUpdateRequest","description":"Field-allow-list for PATCH /admin/subscription-addons/{id}.\n\n``key`` is intentionally NOT in this list — addon rows are looked up by\nkey throughout the backend (see ``core.subscription_addons``), so\nrenaming an active row would orphan every existing reference. Edit via\ndirect SQL if a key really has to change."},"AdminSubscriptionAddonUpdateResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"addon":{"additionalProperties":true,"type":"object","title":"Addon"}},"type":"object","required":["ok","addon"],"title":"AdminSubscriptionAddonUpdateResponse"},"AdminUserActionResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"success":{"type":"boolean","title":"Success"},"user_id":{"type":"integer","title":"User Id"},"status":{"type":"string","title":"Status"}},"type":"object","required":["ok","success","user_id","status"],"title":"AdminUserActionResponse"},"AdminUserCreateRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"send_invite":{"type":"boolean","title":"Send Invite","description":"Send Cognito invitation email to the new user","default":true}},"type":"object","required":["email"],"title":"AdminUserCreateRequest"},"AdminUserCreateResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"user":{"$ref":"#/components/schemas/AdminUserDetail"},"matrix_account_created":{"type":"boolean","title":"Matrix Account Created","default":false},"matrix_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Error"}},"type":"object","required":["ok","user"],"title":"AdminUserCreateResponse"},"AdminUserDetail":{"properties":{"id":{"type":"integer","title":"Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"matrix_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"account_verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Account Verified"},"agreed_terms":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Agreed Terms"},"agreed_privacy":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Agreed Privacy"},"subscription_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Status"},"subscription_plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Plan"},"subscription_ends_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Ends At"},"deletion_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deletion Status"},"deleted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deleted At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"last_signed_in_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Signed In At"},"last_signed_out_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Signed Out At"},"matrix_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Status"},"needs_matrix_password_sync":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Needs Matrix Password Sync"}},"type":"object","required":["id"],"title":"AdminUserDetail"},"AdminUserSecurityFlag":{"properties":{"code":{"type":"string","title":"Code"},"severity":{"type":"string","title":"Severity"},"label":{"type":"string","title":"Label"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"type":"object","required":["code","severity","label"],"title":"AdminUserSecurityFlag"},"AdminUserSecurityResponse":{"properties":{"user_id":{"type":"integer","title":"User Id"},"matrix_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Id"},"sessions":{"items":{"$ref":"#/components/schemas/AdminUserSession"},"type":"array","title":"Sessions"},"matrix_devices":{"items":{"$ref":"#/components/schemas/AdminMatrixDevice"},"type":"array","title":"Matrix Devices"},"matrix_devices_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Devices Error"},"openclaw_instances":{"items":{"$ref":"#/components/schemas/AdminOpenClawInstanceSummary"},"type":"array","title":"Openclaw Instances"},"flags":{"items":{"$ref":"#/components/schemas/AdminUserSecurityFlag"},"type":"array","title":"Flags"}},"type":"object","required":["user_id","sessions","matrix_devices","openclaw_instances","flags"],"title":"AdminUserSecurityResponse"},"AdminUserSession":{"properties":{"id":{"type":"integer","title":"Id"},"device_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Name"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"},"is_revoked":{"type":"boolean","title":"Is Revoked"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"last_seen_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Seen At"}},"type":"object","required":["id","is_revoked"],"title":"AdminUserSession"},"AdminUserUpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"account_verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Account Verified"},"auto_destruct_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auto Destruct Time"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"subscription_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Status"}},"type":"object","title":"AdminUserUpdateRequest"},"AdminUserUpdateResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"user":{"$ref":"#/components/schemas/AdminUserDetail"}},"type":"object","required":["ok","user"],"title":"AdminUserUpdateResponse"},"AdminUserUsageMetric":{"properties":{"used":{"type":"number","title":"Used"},"limit":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Limit"},"unit":{"type":"string","title":"Unit"},"pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct"}},"type":"object","required":["used","unit"],"title":"AdminUserUsageMetric"},"AdminUserUsageResponse":{"properties":{"period":{"type":"string","title":"Period"},"plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Name"},"metrics":{"additionalProperties":{"$ref":"#/components/schemas/AdminUserUsageMetric"},"type":"object","title":"Metrics"},"warnings":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Warnings"},"recent_events":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Recent Events"}},"type":"object","required":["period","plan_name","metrics","warnings","recent_events"],"title":"AdminUserUsageResponse"},"AppleReceiptRequest":{"properties":{"receipt_data":{"type":"string","title":"Receipt Data"},"product_id":{"type":"string","title":"Product Id"}},"type":"object","required":["receipt_data","product_id"],"title":"AppleReceiptRequest"},"AppleReceiptResponse":{"properties":{"status":{"type":"string","title":"Status"},"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["status"],"title":"AppleReceiptResponse"},"AssistantMessage":{"properties":{"role":{"type":"string","title":"Role"},"content":{"type":"string","title":"Content"}},"type":"object","required":["role","content"],"title":"AssistantMessage"},"AssistantRequest":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/AssistantMessage"},"type":"array","title":"Messages"}},"type":"object","required":["messages"],"title":"AssistantRequest"},"AssistantResponse":{"properties":{"reply":{"type":"string","title":"Reply"}},"type":"object","required":["reply"],"title":"AssistantResponse"},"AuditEventItem":{"properties":{"id":{"type":"integer","title":"Id"},"event_type":{"type":"string","title":"Event Type"},"event_detail":{"additionalProperties":true,"type":"object","title":"Event Detail"},"source_ip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Ip"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"},"instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Id"},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"}},"type":"object","required":["id","event_type","event_detail","occurred_at"],"title":"AuditEventItem"},"BotCommand":{"properties":{"syntax":{"type":"string","title":"Syntax"},"description":{"type":"string","title":"Description"},"scope":{"type":"string","enum":["general","support"],"title":"Scope"}},"type":"object","required":["syntax","description","scope"],"title":"BotCommand"},"BotCommandsResponse":{"properties":{"version":{"type":"integer","title":"Version"},"commands":{"items":{"$ref":"#/components/schemas/BotCommand"},"type":"array","title":"Commands"},"user_bot_matrix_ids":{"items":{"type":"string"},"type":"array","title":"User Bot Matrix Ids"},"system_bot_matrix_ids":{"items":{"type":"string"},"type":"array","title":"System Bot Matrix Ids"},"support_room_ids":{"items":{"type":"string"},"type":"array","title":"Support Room Ids"}},"type":"object","required":["version","commands","user_bot_matrix_ids","system_bot_matrix_ids","support_room_ids"],"title":"BotCommandsResponse"},"BotCreateResponse":{"properties":{"id":{"type":"string","title":"Id"},"owner_user_id":{"type":"integer","title":"Owner User Id"},"owner_short_id":{"type":"string","title":"Owner Short Id"},"bot_user_id":{"type":"string","title":"Bot User Id","description":"Full Matrix user ID of the bot"},"bot_name":{"type":"string","title":"Bot Name"},"bot_username":{"type":"string","title":"Bot Username"},"openclaw_connected":{"type":"boolean","title":"Openclaw Connected","description":"Whether an OpenClaw instance is paired"},"runtime":{"type":"string","enum":["openclaw","hermes"],"title":"Runtime","description":"Runtime this bot uses (openclaw or hermes).","default":"openclaw"},"sharing_enabled":{"type":"boolean","title":"Sharing Enabled","description":"Whether this bot can be shared with other users","default":true},"active":{"type":"boolean","title":"Active"},"created_at":{"type":"string","title":"Created At"},"claude_control_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claude Control Mode","description":"Claude Control mode: 'primary', 'backup', or null (off)"},"plan_disabled_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Disabled At","description":"Timestamp when the bot was disabled by a plan downgrade. Null when the bot is fully usable."},"disabled_by_plan":{"type":"boolean","title":"Disabled By Plan","description":"Derived: true iff plan_disabled_at is set. The Matrix account is also deactivated while this is true; clears on re-upgrade.","default":false},"access_token":{"type":"string","title":"Access Token","description":"Raw bot access token — shown once only; store securely"}},"type":"object","required":["id","owner_user_id","owner_short_id","bot_user_id","bot_name","bot_username","openclaw_connected","active","created_at","access_token"],"title":"BotCreateResponse"},"BotDashboardBotStats":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"bot_name":{"type":"string","title":"Bot Name"},"bot_username":{"type":"string","title":"Bot Username"},"status":{"type":"string","title":"Status"},"activity_state":{"type":"string","title":"Activity State"},"messages_received":{"type":"integer","title":"Messages Received"},"messages_sent":{"type":"integer","title":"Messages Sent"},"chunked_messages":{"type":"integer","title":"Chunked Messages"},"total_chunks_sent":{"type":"integer","title":"Total Chunks Sent"},"errors":{"type":"integer","title":"Errors"},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error"},"last_error_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error At"},"uptime_seconds":{"type":"integer","title":"Uptime Seconds"},"rooms_active":{"type":"integer","title":"Rooms Active"},"last_activity_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Activity At"},"machine_hostname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Machine Hostname"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["bot_id","bot_name","bot_username","status","activity_state","messages_received","messages_sent","chunked_messages","total_chunks_sent","errors","last_error","last_error_at","uptime_seconds","rooms_active","last_activity_at","machine_hostname","updated_at"],"title":"BotDashboardBotStats"},"BotDashboardSummary":{"properties":{"total_bots":{"type":"integer","title":"Total Bots"},"online_bots":{"type":"integer","title":"Online Bots"},"total_messages_sent":{"type":"integer","title":"Total Messages Sent"},"total_messages_received":{"type":"integer","title":"Total Messages Received"},"total_errors":{"type":"integer","title":"Total Errors"},"total_rooms_active":{"type":"integer","title":"Total Rooms Active"},"bots":{"items":{"$ref":"#/components/schemas/BotDashboardBotStats"},"type":"array","title":"Bots"}},"type":"object","required":["total_bots","online_bots","total_messages_sent","total_messages_received","total_errors","total_rooms_active","bots"],"title":"BotDashboardSummary"},"BotDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"BotDeleteResponse"},"BotResponse":{"properties":{"id":{"type":"string","title":"Id"},"owner_user_id":{"type":"integer","title":"Owner User Id"},"owner_short_id":{"type":"string","title":"Owner Short Id"},"bot_user_id":{"type":"string","title":"Bot User Id","description":"Full Matrix user ID of the bot"},"bot_name":{"type":"string","title":"Bot Name"},"bot_username":{"type":"string","title":"Bot Username"},"openclaw_connected":{"type":"boolean","title":"Openclaw Connected","description":"Whether an OpenClaw instance is paired"},"runtime":{"type":"string","enum":["openclaw","hermes"],"title":"Runtime","description":"Runtime this bot uses (openclaw or hermes).","default":"openclaw"},"sharing_enabled":{"type":"boolean","title":"Sharing Enabled","description":"Whether this bot can be shared with other users","default":true},"active":{"type":"boolean","title":"Active"},"created_at":{"type":"string","title":"Created At"},"claude_control_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claude Control Mode","description":"Claude Control mode: 'primary', 'backup', or null (off)"},"plan_disabled_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Disabled At","description":"Timestamp when the bot was disabled by a plan downgrade. Null when the bot is fully usable."},"disabled_by_plan":{"type":"boolean","title":"Disabled By Plan","description":"Derived: true iff plan_disabled_at is set. The Matrix account is also deactivated while this is true; clears on re-upgrade.","default":false}},"type":"object","required":["id","owner_user_id","owner_short_id","bot_user_id","bot_name","bot_username","openclaw_connected","active","created_at"],"title":"BotResponse"},"BotRoomRemoveResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"BotRoomRemoveResponse"},"BotRoomResponse":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"room_id":{"type":"string","title":"Room Id"},"mode":{"type":"string","title":"Mode"},"added_at":{"type":"string","title":"Added At"}},"type":"object","required":["bot_id","room_id","mode","added_at"],"title":"BotRoomResponse"},"BotRuntimeDetail":{"properties":{"botId":{"type":"string","title":"Botid"},"botName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Botname"},"botUsername":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Botusername"},"botUserId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Botuserid"},"status":{"type":"string","title":"Status","default":"unknown"},"activityState":{"type":"string","title":"Activitystate","default":"unknown"},"activeTask":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Activetask"},"lastActivityAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lastactivityat"},"messagesReceived":{"type":"integer","title":"Messagesreceived","default":0},"messagesSent":{"type":"integer","title":"Messagessent","default":0},"chunkedMessages":{"type":"integer","title":"Chunkedmessages","default":0},"totalChunksSent":{"type":"integer","title":"Totalchunkssent","default":0},"errors":{"type":"integer","title":"Errors","default":0},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lasterror"},"lastErrorAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lasterrorat"},"uptimeSeconds":{"type":"integer","title":"Uptimeseconds","default":0},"roomsActive":{"type":"integer","title":"Roomsactive","default":0},"roomDetails":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Roomdetails"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updatedat"},"claudeCodeEnabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Claudecodeenabled"},"claudeCodeSessionId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claudecodesessionid"},"healthScore":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Healthscore"},"pairingPhase":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pairingphase"},"failureReason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failurereason"},"skills":{"anyOf":[{"items":{"$ref":"#/components/schemas/SkillSummary"},"type":"array"},{"type":"null"}],"title":"Skills"}},"type":"object","required":["botId"],"title":"BotRuntimeDetail"},"BotStatus":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"status":{"type":"string","title":"Status","default":"unknown"},"activity_state":{"type":"string","title":"Activity State","default":"unknown"},"active_task":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Active Task"},"last_activity_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Activity At"},"messages_received":{"type":"integer","title":"Messages Received","default":0},"messages_sent":{"type":"integer","title":"Messages Sent","default":0},"chunked_messages":{"type":"integer","title":"Chunked Messages","default":0},"total_chunks_sent":{"type":"integer","title":"Total Chunks Sent","default":0},"errors":{"type":"integer","title":"Errors","default":0},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error"},"last_error_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error At"},"uptime_seconds":{"type":"integer","title":"Uptime Seconds","default":0},"rooms_active":{"type":"integer","title":"Rooms Active","default":0},"room_details":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Room Details"},"claude_code_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Claude Code Enabled"},"claude_code_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claude Code Session Id"},"quarantined":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Quarantined"},"skill_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Skill Count"},"skills":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Skills"}},"type":"object","required":["bot_id"],"title":"BotStatus"},"BugReportRequest":{"properties":{"text":{"type":"string","title":"Text"},"can_contact":{"type":"boolean","title":"Can Contact","default":false},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Email"},"app_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"App Version"},"os":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Os"},"device_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Id"}},"type":"object","required":["text"],"title":"BugReportRequest"},"CancelResponse":{"properties":{"status":{"type":"string","title":"Status"},"message":{"type":"string","title":"Message"}},"type":"object","required":["status","message"],"title":"CancelResponse"},"CheckoutRequest":{"properties":{"price_id":{"type":"string","title":"Price Id"},"return_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Return To"}},"type":"object","required":["price_id"],"title":"CheckoutRequest"},"CheckoutResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url","description":"Stripe Checkout Session URL"}},"type":"object","required":["checkout_url"],"title":"CheckoutResponse"},"CliAuthCallbackResponse":{"properties":{"success":{"type":"boolean","title":"Success"}},"type":"object","required":["success"],"title":"CliAuthCallbackResponse"},"CliAuthStartResponse":{"properties":{"auth_url":{"type":"string","title":"Auth Url","description":"URL to open in browser to complete authentication"},"code":{"type":"string","title":"Code","description":"Temporary code for polling"}},"type":"object","required":["auth_url","code"],"title":"CliAuthStartResponse"},"CloudVmResponse":{"properties":{"instance_id":{"type":"string","title":"Instance Id"},"orgo_computer_id":{"type":"string","title":"Orgo Computer Id"},"provision_status":{"type":"string","title":"Provision Status"},"provision_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provision Detail"}},"type":"object","required":["instance_id","orgo_computer_id","provision_status"],"title":"CloudVmResponse"},"CommandResponse":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","title":"Status"},"commandType":{"type":"string","title":"Commandtype"}},"type":"object","required":["id","status","commandType"],"title":"CommandResponse"},"CommandResultRequest":{"properties":{"status":{"type":"string","pattern":"^(success|failed)$","title":"Status"},"result":{"type":"string","title":"Result"},"new_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"New Version"}},"type":"object","required":["status","result"],"title":"CommandResultRequest"},"CommandStatusResponse":{"properties":{"id":{"type":"string","title":"Id"},"commandType":{"type":"string","title":"Commandtype"},"status":{"type":"string","title":"Status"},"result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result"},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Createdat"},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completedat"}},"type":"object","required":["id","commandType","status"],"title":"CommandStatusResponse"},"CompatRunDeleteResponse":{"properties":{"deleted":{"type":"integer","title":"Deleted"}},"type":"object","required":["deleted"],"title":"CompatRunDeleteResponse"},"CompatRunIn":{"properties":{"runtime":{"type":"string","title":"Runtime","default":"openclaw"},"openclaw_version":{"type":"string","title":"Openclaw Version"},"plugin_version":{"type":"string","title":"Plugin Version"},"cli_version":{"type":"string","title":"Cli Version"},"started_at":{"type":"string","title":"Started At"},"finished_at":{"type":"string","title":"Finished At"},"host":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Host"},"result":{"type":"string","title":"Result"},"scenarios":{"items":{"$ref":"#/components/schemas/CompatScenarioOut"},"type":"array","title":"Scenarios"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"log_artifact_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Log Artifact Url"}},"type":"object","required":["openclaw_version","plugin_version","cli_version","started_at","finished_at","result","scenarios"],"title":"CompatRunIn","description":"Webhook payload — matches the JSON the harness writes in\nbadgerclaw-openclaw-compat/harness/report.ts (CompatReport)."},"CompatRunOut":{"properties":{"id":{"type":"integer","title":"Id"},"runtime":{"type":"string","title":"Runtime","default":"openclaw"},"openclaw_version":{"type":"string","title":"Openclaw Version"},"plugin_version":{"type":"string","title":"Plugin Version"},"cli_version":{"type":"string","title":"Cli Version"},"result":{"type":"string","title":"Result"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"scenarios":{"items":{"$ref":"#/components/schemas/CompatScenarioOut"},"type":"array","title":"Scenarios"},"log_artifact_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Log Artifact Url"},"triggered_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Triggered By"},"started_at":{"type":"string","title":"Started At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","openclaw_version","plugin_version","cli_version","result","summary","scenarios","log_artifact_url","triggered_by","started_at","finished_at","created_at"],"title":"CompatRunOut"},"CompatRunWebhookResponse":{"properties":{"id":{"type":"integer","title":"Id"},"created":{"type":"boolean","title":"Created"}},"type":"object","required":["id","created"],"title":"CompatRunWebhookResponse"},"CompatScenarioOut":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"status":{"type":"string","title":"Status"},"duration_ms":{"type":"integer","title":"Duration Ms"},"error_excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Excerpt"},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["id","name","status","duration_ms"],"title":"CompatScenarioOut"},"CreateBotRequest":{"properties":{"bot_name":{"type":"string","maxLength":255,"minLength":1,"title":"Bot Name","description":"Display name for the bot"},"bot_username":{"type":"string","maxLength":100,"minLength":1,"pattern":"^[a-z0-9_]+$","title":"Bot Username","description":"Lowercase alphanumeric username (underscores allowed). '_bot' suffix added automatically.","example":"myassistant"},"runtime":{"type":"string","enum":["openclaw","hermes"],"title":"Runtime","description":"Runtime to spawn this bot under. 'openclaw' (default) uses the existing plugin pair flow; 'hermes' provisions a containerised Hermes agent on the assigned host. The Hermes path requires a host that advertises capabilities.hermes.installed and is gated behind the HERMES_RUNTIME_ENABLED feature flag in this API deployment.","default":"openclaw"}},"type":"object","required":["bot_name","bot_username"],"title":"CreateBotRequest"},"CreateCloudVmRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Name","description":"Human-readable VM name. Defaults to 'bc-<short-id>'."},"cpu":{"type":"integer","maximum":16.0,"minimum":1.0,"title":"Cpu","description":"vCPUs (orgo allows {1,2,4,8,16})","default":2},"ram":{"type":"integer","maximum":64.0,"minimum":4.0,"title":"Ram","description":"RAM in GB (orgo allows {4,8,16,32,64})","default":8},"disk_size_gb":{"anyOf":[{"type":"integer","maximum":200.0,"minimum":8.0},{"type":"null"}],"title":"Disk Size Gb","description":"Optional disk size in GB; defaults to plan."},"llm_provider":{"type":"string","pattern":"^(gemini|anthropic|openrouter)$","title":"Llm Provider","description":"LLM provider whose key powers every Hermes bot on this VM."},"llm_api_key":{"type":"string","maxLength":512,"minLength":8,"title":"Llm Api Key","description":"API key for the chosen LLM provider. Stored encrypted (KMS)."}},"type":"object","required":["llm_provider","llm_api_key"],"title":"CreateCloudVmRequest","description":"Provision a cloud VM in the BadgerClaw-owned Orgo workspace.\n\nThe user picks size only; the workspace and credentials live server-side.\n\nCloud VMs are Hermes-only, and each Hermes container needs an LLM\nprovider key in its environment. We collect the key on machine create\n(per-machine, not per-bot) and store it encrypted, then inject it into\nevery container the user pairs to this machine."},"CreateCommandRequest":{"properties":{"instance_id":{"type":"string","maxLength":255,"minLength":1,"title":"Instance Id"},"command_type":{"type":"string","pattern":"^(update_cli|update_plugin|restart_gateway|start_claude_code|stop_claude_code|start_claude_control|stop_claude_control|update_claude_tools|bot_share_notify|bot_share_revoked|bot_refresh|install_skill)$","title":"Command Type"},"payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload"}},"type":"object","required":["instance_id","command_type"],"title":"CreateCommandRequest"},"CreateCrossBotGroupRequest":{"properties":{"from_bot_user_id":{"type":"string","title":"From Bot User Id","description":"Matrix user ID of the initiating bot"},"to_bot_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Bot User Id","description":"Matrix user ID of a single target bot (legacy; prefer to_bot_user_ids)"},"to_bot_user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"To Bot User Ids","description":"Matrix user IDs of target bots. Pass this to create ONE group room with the user + initiating bot + all listed target bots."},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Matrix user ID of the human user to include. If omitted or empty, the authenticated caller's matrix_id is used."},"room_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Room Name","description":"Custom room name (auto-generated if omitted)"},"question":{"type":"string","title":"Question","description":"The question/message Bot A sends to the target bot(s)"}},"type":"object","required":["from_bot_user_id","question"],"title":"CreateCrossBotGroupRequest","description":"Request to create a group chat for cross-bot conversation.\n\nSupports either one target bot (legacy ``to_bot_user_id``) or many\n(``to_bot_user_ids``). When both are supplied the union is used.\nCallers are encouraged to pass all intended bots in a single request so\nthe user gets ONE multi-party room, not one room per bot."},"CreateCrossBotGroupResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"room_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Room Id"},"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Id"},"event_ids":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Event Ids"},"target_bot_user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Target Bot User Ids"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["success"],"title":"CreateCrossBotGroupResponse"},"CreatePairingRequest":{"properties":{"bot_id":{"type":"string","title":"Bot Id","description":"UUID of the bot to generate a pairing code for"},"target_instance_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Target Instance Id","description":"Optional OpenClaw instance_id this code is intended to be redeemed by. When present, the caller must own or collaborate on that instance (403 otherwise). When omitted, the code is untargeted — legacy behavior where any eligible instance of the bot owner may redeem (useful for single-instance users and for the 'Pair wherever' UX). This PR only records the field; /pending-pairs scoping (2.2) and /redeem enforcement (2.3) land in follow-up PRs.","example":"openclaw-srv1552967-5dadc19f78a3c4b8"}},"type":"object","required":["bot_id"],"title":"CreatePairingRequest"},"CreatePairingResponse":{"properties":{"code":{"type":"string","title":"Code","description":"Pairing code in BCK-XXXX-XXXX format","example":"BCK-A1B2-C3D4"},"expires_in":{"type":"integer","title":"Expires In","description":"Seconds until the code expires"},"bot_name":{"type":"string","title":"Bot Name"},"bot_user_id":{"type":"string","title":"Bot User Id","description":"Full Matrix user ID of the bot"},"target_instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Instance Id","description":"Echo of the target instance the code was minted for (null for an untargeted code). Lets the iOS caller reflect the selection back in the pair sheet without an extra round-trip."}},"type":"object","required":["code","expires_in","bot_name","bot_user_id"],"title":"CreatePairingResponse"},"CreateShareRequest":{"properties":{"shared_with_user_id":{"type":"string","maxLength":255,"minLength":1,"title":"Shared With User Id","description":"Matrix user ID to share the bot with"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","description":"Optional ISO-8601 expiry timestamp"}},"type":"object","required":["shared_with_user_id"],"title":"CreateShareRequest"},"CrossBotMessageRequest":{"properties":{"from_bot_user_id":{"type":"string","title":"From Bot User Id","description":"Matrix user ID of the sending bot"},"to_bot_user_id":{"type":"string","title":"To Bot User Id","description":"Matrix user ID of the target bot"},"message":{"type":"string","title":"Message","description":"The message/question to send"},"room_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Room Id","description":"Room to send in. If omitted, finds a shared room automatically."}},"type":"object","required":["from_bot_user_id","to_bot_user_id","message"],"title":"CrossBotMessageRequest","description":"Request for one bot to send an @mention message to another bot."},"CrossBotMessageResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Id"},"room_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Room Id"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["success"],"title":"CrossBotMessageResponse"},"DbHealthResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"database":{"type":"string","title":"Database"}},"type":"object","required":["ok","database"],"title":"DbHealthResponse"},"DeleteAccountRequest":{"properties":{"password":{"type":"string","minLength":1,"title":"Password"}},"type":"object","required":["password"],"title":"DeleteAccountRequest"},"DeleteAccountResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"DeleteAccountResponse"},"DeleteFileRequest":{"properties":{"file_url":{"type":"string","title":"File Url","description":"Full S3 file URL to generate a delete presigned URL for"}},"type":"object","required":["file_url"],"title":"DeleteFileRequest"},"DeletePresignedUrlResponse":{"properties":{"delete_url":{"type":"string","title":"Delete Url","description":"Pre-signed S3 DELETE URL"},"upload_url":{"type":"string","title":"Upload Url","description":"Alias for delete_url (backwards compat)"}},"type":"object","required":["delete_url","upload_url"],"title":"DeletePresignedUrlResponse"},"DeviceCheckRequest":{"properties":{"device_token":{"type":"string","title":"Device Token"}},"type":"object","required":["device_token"],"title":"DeviceCheckRequest"},"DeviceCheckResponse":{"properties":{"allowed":{"type":"boolean","title":"Allowed"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["allowed"],"title":"DeviceCheckResponse"},"DeviceDeactivateResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"DeviceDeactivateResponse"},"DeviceDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"DeviceDeleteResponse"},"DeviceTokenInfo":{"properties":{"id":{"type":"integer","title":"Id"},"device_token":{"type":"string","title":"Device Token"},"environment":{"type":"string","title":"Environment"},"app_id":{"type":"string","title":"App Id"},"platform":{"type":"string","title":"Platform"},"device_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Name"},"app_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"App Version"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"}},"type":"object","required":["id","device_token","environment","app_id","platform","is_active","created_at"],"title":"DeviceTokenInfo"},"DisconnectRequest":{"properties":{"instance_id":{"type":"string","title":"Instance Id","description":"instance_id of the machine going offline"}},"type":"object","required":["instance_id"],"title":"DisconnectRequest"},"DisconnectResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"}},"type":"object","required":["ok"],"title":"DisconnectResponse"},"DowngradeItem":{"properties":{"id":{"type":"string","title":"Id"},"kind":{"type":"string","title":"Kind"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Id"},"bot_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bot User Id"},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen"}},"type":"object","required":["id","kind"],"title":"DowngradeItem","description":"A resource the user can choose to keep. One entry per countable thing:\nan OpenClaw instance (owned or collaborator) or a bot."},"EmailAvailabilityResponse":{"properties":{"available":{"type":"boolean","title":"Available"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["available","reason"],"title":"EmailAvailabilityResponse"},"FeatureDowngradeState":{"properties":{"feature":{"type":"string","title":"Feature"},"limit":{"type":"integer","title":"Limit"},"current_count":{"type":"integer","title":"Current Count"},"items":{"items":{"$ref":"#/components/schemas/DowngradeItem"},"type":"array","title":"Items"},"resolved":{"type":"boolean","title":"Resolved","default":false}},"type":"object","required":["feature","limit","current_count","items"],"title":"FeatureDowngradeState","description":"Over-cap state for one gate."},"FeaturedRoomAcknowledgeResponse":{"properties":{"onboarded_at":{"type":"string","format":"date-time","title":"Onboarded At"}},"type":"object","required":["onboarded_at"],"title":"FeaturedRoomAcknowledgeResponse"},"FeaturedRoomAdminItem":{"properties":{"room_id":{"type":"string","title":"Room Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"matrix_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Name"},"matrix_topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Topic"},"matrix_avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Avatar Url"},"matrix_canonical_alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Canonical Alias"},"matrix_joined_member_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matrix Joined Member Count"},"display_order":{"type":"integer","title":"Display Order"},"added_by":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Added By"},"added_at":{"type":"string","format":"date-time","title":"Added At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["room_id","display_name","description","matrix_name","matrix_topic","matrix_avatar_url","matrix_canonical_alias","matrix_joined_member_count","display_order","added_by","added_at","updated_at"],"title":"FeaturedRoomAdminItem"},"FeaturedRoomAdminListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FeaturedRoomAdminItem"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"FeaturedRoomAdminListResponse"},"FeaturedRoomCreateRequest":{"properties":{"room_id":{"type":"string","title":"Room Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"display_order":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Display Order"},"create_if_missing":{"type":"boolean","title":"Create If Missing","default":true}},"type":"object","required":["room_id"],"title":"FeaturedRoomCreateRequest"},"FeaturedRoomUpdateRequest":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"display_order":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Display Order"},"refresh_metadata":{"type":"boolean","title":"Refresh Metadata","default":false}},"type":"object","title":"FeaturedRoomUpdateRequest"},"FeaturedRoomUserItem":{"properties":{"room_id":{"type":"string","title":"Room Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"canonical_alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Alias"},"joined_member_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Joined Member Count"}},"type":"object","required":["room_id","name","description","topic","avatar_url","canonical_alias","joined_member_count"],"title":"FeaturedRoomUserItem"},"FeaturedRoomUserListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FeaturedRoomUserItem"},"type":"array","title":"Items"},"viewer_onboarded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Viewer Onboarded At"}},"type":"object","required":["items"],"title":"FeaturedRoomUserListResponse"},"ForgotPasswordRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"ForgotPasswordRequest"},"ForgotPasswordResponse":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"ForgotPasswordResponse"},"GatewayRestartRequest":{"properties":{"instance_id":{"type":"string","maxLength":255,"minLength":1,"title":"Instance Id"}},"type":"object","required":["instance_id"],"title":"GatewayRestartRequest"},"GatewayRestartResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"message":{"type":"string","title":"Message"}},"type":"object","required":["ok","message"],"title":"GatewayRestartResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"status":{"type":"string","title":"Status"},"timestamp":{"type":"string","title":"Timestamp"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["ok","status","timestamp"],"title":"HealthResponse"},"HeartbeatPayload":{"properties":{"instance_id":{"type":"string","maxLength":255,"minLength":1,"title":"Instance Id"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hostname"},"os":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Os"},"arch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arch"},"cli_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cli Version"},"plugin_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plugin Version"},"mem_free_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mem Free Mb"},"uptime_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Uptime Seconds"},"gateway_status":{"type":"string","title":"Gateway Status","default":"unknown"},"gateway_pid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gateway Pid"},"last_gateway_restart":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Gateway Restart"},"bots":{"items":{"$ref":"#/components/schemas/BotStatus"},"type":"array","title":"Bots"},"capabilities":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Capabilities"}},"type":"object","required":["instance_id"],"title":"HeartbeatPayload"},"HeartbeatResponseV2":{"properties":{"ok":{"type":"boolean","title":"Ok"},"pending_commands":{"items":{"$ref":"#/components/schemas/PendingCommandItem"},"type":"array","title":"Pending Commands"}},"type":"object","required":["ok"],"title":"HeartbeatResponseV2"},"HermesLogTailResponse":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"lines":{"items":{"type":"string"},"type":"array","title":"Lines"},"truncated":{"type":"boolean","title":"Truncated"}},"type":"object","required":["bot_id","lines","truncated"],"title":"HermesLogTailResponse"},"HermesRestartResponse":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"restarted":{"type":"boolean","title":"Restarted"},"message":{"type":"string","title":"Message"}},"type":"object","required":["bot_id","restarted","message"],"title":"HermesRestartResponse"},"HermesRuntimeBootstrapRequest":{"properties":{"recovery_key":{"type":"string","maxLength":200,"minLength":32,"title":"Recovery Key"},"image_ref":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Image Ref"}},"type":"object","required":["recovery_key"],"title":"HermesRuntimeBootstrapRequest"},"HermesRuntimeBootstrapResponse":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"persisted":{"type":"boolean","title":"Persisted"},"bootstrapped_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Bootstrapped At"},"runtime_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime Version"}},"type":"object","required":["bot_id","persisted","bootstrapped_at","runtime_version"],"title":"HermesRuntimeBootstrapResponse"},"HermesVersionResponse":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image"},"container_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Container Id"}},"type":"object","required":["bot_id","image","container_id"],"title":"HermesVersionResponse"},"InFlightCloudVMItem":{"properties":{"instance_id":{"type":"string","title":"Instance Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"provision_status":{"type":"string","title":"Provision Status"},"provision_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provision Detail"}},"type":"object","required":["instance_id","provision_status"],"title":"InFlightCloudVMItem","description":"A single cloud VM that is mid-bring-up (booting/installing/setup).\n\nReturned by ``GET /openclaw/cloud-vm/in-flight`` so a client that was\nkilled (or signed out) during a long provision can recover the run on\nnext launch: the server is the source of truth, the local Task is just\na polling loop that listens to it."},"InstanceResponse":{"properties":{"instance_id":{"type":"string","title":"Instance Id"},"label":{"type":"string","title":"Label"},"version":{"type":"string","title":"Version"},"online":{"type":"boolean","title":"Online"},"capabilities":{"additionalProperties":true,"type":"object","title":"Capabilities"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"orgo_workspace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgo Workspace Id"},"orgo_workspace_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgo Workspace Name"},"orgo_computer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgo Computer Id"}},"type":"object","required":["instance_id","label","version","online"],"title":"InstanceResponse"},"KmsHealthResponse":{"properties":{"kms_arn_set":{"type":"boolean","title":"Kms Arn Set"},"kms_client_initialized":{"type":"boolean","title":"Kms Client Initialized"},"kms_key_arn_set":{"type":"boolean","title":"Kms Key Arn Set"},"status":{"type":"string","title":"Status"},"encryption_test":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Encryption Test"}},"additionalProperties":true,"type":"object","required":["kms_arn_set","kms_client_initialized","kms_key_arn_set","status"],"title":"KmsHealthResponse"},"LeaveRoomRequest":{"properties":{"roomId":{"type":"string","title":"Roomid"}},"type":"object","required":["roomId"],"title":"LeaveRoomRequest"},"LoginRequest":{"properties":{"username":{"type":"string","minLength":1,"title":"Username"},"password":{"type":"string","minLength":1,"title":"Password"}},"type":"object","required":["username","password"],"title":"LoginRequest"},"LoginResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"access_token":{"type":"string","title":"Access Token"},"id_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id Token"},"refresh_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refresh Token"},"expires_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires In"},"token_type":{"type":"string","title":"Token Type","default":"Bearer"},"user_profile":{"$ref":"#/components/schemas/UserProfileInLogin"},"matrix_recovery_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Recovery Key"},"session_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Session Id"}},"type":"object","required":["success","message","access_token","user_profile"],"title":"LoginResponse"},"LogoutRequest":{"properties":{"device_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Token","description":"APNs/FCM device token to deregister"},"refresh_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refresh Token","description":"Refresh token to revoke for per-device logout"},"session_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Session Id","description":"Session ID to delete"}},"type":"object","title":"LogoutRequest"},"LogoutResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"user_email":{"type":"string","title":"User Email"},"matrix_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Id"},"device_token_deactivated":{"type":"boolean","title":"Device Token Deactivated"},"logout_timestamp":{"type":"string","title":"Logout Timestamp"}},"type":"object","required":["success","message","user_email","device_token_deactivated","logout_timestamp"],"title":"LogoutResponse"},"MachineDetailResponse":{"properties":{"instanceId":{"type":"string","title":"Instanceid"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hostname"},"os":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Os"},"arch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arch"},"cliVersion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cliversion"},"pluginVersion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pluginversion"},"memFreeMb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Memfreemb"},"uptimeSeconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Uptimeseconds"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"orgoWorkspaceId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgoworkspaceid"},"orgoWorkspaceName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgoworkspacename"},"orgoComputerId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgocomputerid"},"provisionStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provisionstatus"},"isOnline":{"type":"boolean","title":"Isonline"},"lastHeartbeat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lastheartbeat"},"gatewayStatus":{"type":"string","title":"Gatewaystatus","default":"unknown"},"hasOpenclaw":{"type":"boolean","title":"Hasopenclaw","default":true},"hasHermes":{"type":"boolean","title":"Hashermes","default":false},"gatewayPid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gatewaypid"},"lastGatewayRestart":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lastgatewayrestart"},"bots":{"items":{"$ref":"#/components/schemas/BotRuntimeDetail"},"type":"array","title":"Bots","default":[]}},"type":"object","required":["instanceId","isOnline"],"title":"MachineDetailResponse"},"MachineListBotItem":{"properties":{"botId":{"type":"string","title":"Botid"},"botName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Botname"},"botUsername":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Botusername"},"status":{"type":"string","title":"Status","default":"unknown"},"activityState":{"type":"string","title":"Activitystate","default":"unknown"},"activeTask":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Activetask"},"claudeCodeEnabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Claudecodeenabled"},"claudeCodeSessionId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claudecodesessionid"},"roomsActive":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Roomsactive"},"healthScore":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Healthscore"},"pairingPhase":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pairingphase"},"failureReason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failurereason"},"skillCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Skillcount"}},"type":"object","required":["botId"],"title":"MachineListBotItem"},"MachineListItem":{"properties":{"instanceId":{"type":"string","title":"Instanceid"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hostname"},"os":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Os"},"arch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arch"},"cliVersion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cliversion"},"pluginVersion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pluginversion"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"orgoWorkspaceId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgoworkspaceid"},"orgoWorkspaceName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgoworkspacename"},"orgoComputerId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgocomputerid"},"provisionStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provisionstatus"},"isOnline":{"type":"boolean","title":"Isonline"},"lastHeartbeat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lastheartbeat"},"gatewayStatus":{"type":"string","title":"Gatewaystatus","default":"unknown"},"hasOpenclaw":{"type":"boolean","title":"Hasopenclaw","default":true},"hasHermes":{"type":"boolean","title":"Hashermes","default":false},"botCount":{"type":"integer","title":"Botcount","default":0},"bots":{"items":{"$ref":"#/components/schemas/MachineListBotItem"},"type":"array","title":"Bots","default":[]}},"type":"object","required":["instanceId","isOnline"],"title":"MachineListItem"},"MachinesListResponse":{"properties":{"machines":{"items":{"$ref":"#/components/schemas/MachineListItem"},"type":"array","title":"Machines"}},"type":"object","required":["machines"],"title":"MachinesListResponse"},"ManualDowngradeRequest":{"properties":{"to_plan":{"type":"string","title":"To Plan","description":"Name of the plan to downgrade to (e.g. 'free', 'solo')"}},"type":"object","required":["to_plan"],"title":"ManualDowngradeRequest"},"MatrixDeactivateUserRequest":{"properties":{"erase":{"type":"boolean","title":"Erase","description":"Whether to erase user data","default":false}},"type":"object","title":"MatrixDeactivateUserRequest","description":"Request to deactivate Matrix user"},"MatrixDeleteRoomRequest":{"properties":{"block":{"type":"boolean","title":"Block","description":"Block room from being created again","default":false},"purge":{"type":"boolean","title":"Purge","description":"Purge room from database","default":true}},"type":"object","title":"MatrixDeleteRoomRequest","description":"Request to delete Matrix room"},"MatrixLoginRequest":{"properties":{"username":{"type":"string","title":"Username","description":"Matrix username (localpart or full user ID)","example":"alice"},"password":{"type":"string","title":"Password","description":"User password","example":"s3cr3tP@ss!"}},"type":"object","required":["username","password"],"title":"MatrixLoginRequest","description":"Credentials for Matrix client login."},"MatrixLoginResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"Matrix access token"},"user_id":{"type":"string","title":"User Id","description":"Full Matrix user ID","example":"@alice:badger.signout.io"},"device_id":{"type":"string","title":"Device Id","description":"Matrix device ID"}},"type":"object","required":["access_token","user_id","device_id"],"title":"MatrixLoginResponse","description":"Successful Matrix client login tokens."},"MatrixResetPasswordRequest":{"properties":{"new_password":{"type":"string","minLength":8,"title":"New Password","description":"New password"},"logout_devices":{"type":"boolean","title":"Logout Devices","description":"Logout all devices","default":true}},"type":"object","required":["new_password"],"title":"MatrixResetPasswordRequest","description":"Request to reset Matrix user password"},"MatrixRoomMembersResponse":{"properties":{"members":{"items":{"type":"string"},"type":"array","title":"Members"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["members","total"],"title":"MatrixRoomMembersResponse","description":"Response for Matrix room members"},"MatrixRoomMeta":{"properties":{"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"ISO-8601 UTC timestamp, or null if unavailable"}},"type":"object","title":"MatrixRoomMeta"},"MatrixRoomResponse":{"properties":{"room_id":{"type":"string","title":"Room Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"canonical_alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Alias"},"joined_members":{"type":"integer","title":"Joined Members"},"joined_local_members":{"type":"integer","title":"Joined Local Members"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version"},"creator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Creator"},"encryption":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Encryption"},"federatable":{"type":"boolean","title":"Federatable"},"public":{"type":"boolean","title":"Public"},"join_rules":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Join Rules"},"guest_access":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Guest Access"},"history_visibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"History Visibility"},"state_events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"State Events"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"joined_local_devices":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Joined Local Devices"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["room_id","joined_members","joined_local_members","federatable","public"],"title":"MatrixRoomResponse","description":"Matrix room information"},"MatrixRoomsListResponse":{"properties":{"rooms":{"items":{"$ref":"#/components/schemas/MatrixRoomResponse"},"type":"array","title":"Rooms"},"total_rooms":{"type":"integer","title":"Total Rooms"},"next_batch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Batch"}},"type":"object","required":["rooms","total_rooms"],"title":"MatrixRoomsListResponse","description":"Response for listing Matrix rooms"},"MatrixRoomsMetaRequest":{"properties":{"room_ids":{"items":{"type":"string"},"type":"array","title":"Room Ids","description":"Room IDs to fetch creation metadata for"}},"type":"object","required":["room_ids"],"title":"MatrixRoomsMetaRequest"},"MatrixRoomsMetaResponse":{"properties":{"rooms":{"additionalProperties":{"$ref":"#/components/schemas/MatrixRoomMeta"},"type":"object","title":"Rooms"}},"type":"object","required":["rooms"],"title":"MatrixRoomsMetaResponse"},"MatrixServerStatsResponse":{"properties":{"media":{"additionalProperties":true,"type":"object","title":"Media"},"users":{"additionalProperties":true,"type":"object","title":"Users"},"rooms":{"additionalProperties":true,"type":"object","title":"Rooms"}},"type":"object","title":"MatrixServerStatsResponse","description":"Response for Matrix server statistics"},"MatrixServerVersionResponse":{"properties":{"server_version":{"type":"string","title":"Server Version"},"python_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Python Version"}},"type":"object","required":["server_version"],"title":"MatrixServerVersionResponse","description":"Response for Matrix server version"},"MatrixTestEndpointRequest":{"properties":{"endpoint":{"type":"string","title":"Endpoint","description":"Matrix endpoint path (e.g., '/_synapse/admin/v2/users')"},"method":{"type":"string","title":"Method","description":"HTTP method (GET, POST, PUT, DELETE)","default":"GET"},"body":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Body","description":"Optional request body"}},"type":"object","required":["endpoint"],"title":"MatrixTestEndpointRequest","description":"Request to test arbitrary Matrix endpoint"},"MatrixTestEndpointResponse":{"properties":{"status":{"type":"integer","title":"Status"},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers"},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"success":{"type":"boolean","title":"Success","default":true},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"errcode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Errcode"}},"type":"object","required":["status","headers"],"title":"MatrixTestEndpointResponse","description":"Response from Matrix endpoint test"},"MatrixUserResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"displayname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Displayname"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"admin":{"type":"boolean","title":"Admin"},"deactivated":{"type":"boolean","title":"Deactivated"},"is_guest":{"type":"boolean","title":"Is Guest"},"creation_ts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Creation Ts"},"shadow_banned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Shadow Banned"},"erased":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Erased"},"locked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Locked"}},"type":"object","required":["user_id","admin","deactivated","is_guest"],"title":"MatrixUserResponse","description":"Matrix user information"},"MatrixUsersListResponse":{"properties":{"users":{"items":{"$ref":"#/components/schemas/MatrixUserResponse"},"type":"array","title":"Users"},"total":{"type":"integer","title":"Total"},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Token"}},"type":"object","required":["users","total"],"title":"MatrixUsersListResponse","description":"Response for listing Matrix users"},"MigrateRuntimeRequest":{"properties":{"runtime":{"type":"string","title":"Runtime"}},"type":"object","required":["runtime"],"title":"MigrateRuntimeRequest"},"MintTokenRequest":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"title":"Name","description":"User-provided label, e.g. 'fly-clawstation'. Must be unique within the user's non-revoked tokens."},"expires_in":{"type":"string","title":"Expires In","description":"How long the token should live. One of: 1h, 1y, 24h, 30d, 7d, 90d, never. 'never' requires confirm_no_expiry=true.","default":"90d"},"confirm_no_expiry":{"type":"boolean","title":"Confirm No Expiry","description":"Must be true if expires_in='never'. Logged in the audit trail.","default":false}},"type":"object","required":["name"],"title":"MintTokenRequest"},"MintTokenResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"token":{"type":"string","title":"Token","description":"The plaintext access token. ONLY returned here, never again. Store it now — it cannot be recovered."},"token_prefix":{"type":"string","title":"Token Prefix","description":"Short display prefix of the token (safe to show in UIs)."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"bound_instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bound Instance Id"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"usage_note":{"type":"string","title":"Usage Note","default":"Save this value now — it cannot be recovered. Revoke and re-mint if lost. Pass it as `Authorization: Bearer <token>` on API calls."}},"type":"object","required":["id","name","token","token_prefix","created_at","scopes"],"title":"MintTokenResponse"},"NotificationHistoryResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"notifications":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Notifications","description":"List of notification records"},"count":{"type":"integer","title":"Count","description":"Number of notifications returned"}},"type":"object","required":["success","count"],"title":"NotificationHistoryResponse"},"OverviewResponse":{"properties":{"totalBots":{"type":"integer","title":"Totalbots"},"onlineBots":{"type":"integer","title":"Onlinebots"},"offlineBots":{"type":"integer","title":"Offlinebots"},"undeployedBots":{"type":"integer","title":"Undeployedbots","default":0},"errorBots":{"type":"integer","title":"Errorbots"},"workingBots":{"type":"integer","title":"Workingbots","default":0},"idleBots":{"type":"integer","title":"Idlebots","default":0},"stalledBots":{"type":"integer","title":"Stalledbots","default":0},"totalMachines":{"type":"integer","title":"Totalmachines"},"onlineMachines":{"type":"integer","title":"Onlinemachines"},"totalMessagesSent":{"type":"integer","title":"Totalmessagessent"},"totalMessagesReceived":{"type":"integer","title":"Totalmessagesreceived"},"totalChunkedMessages":{"type":"integer","title":"Totalchunkedmessages"},"totalErrors":{"type":"integer","title":"Totalerrors"}},"type":"object","required":["totalBots","onlineBots","offlineBots","errorBots","totalMachines","onlineMachines","totalMessagesSent","totalMessagesReceived","totalChunkedMessages","totalErrors"],"title":"OverviewResponse"},"PaymentHistoryItem":{"properties":{"id":{"type":"string","title":"Id"},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Number"},"status":{"type":"string","title":"Status"},"amount_paid":{"type":"integer","title":"Amount Paid","description":"Amount paid in the invoice's smallest currency unit (e.g. cents)"},"currency":{"type":"string","title":"Currency"},"created":{"type":"integer","title":"Created","description":"UNIX timestamp when the invoice was created"},"period_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Start"},"period_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period End"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"hosted_invoice_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hosted Invoice Url"},"invoice_pdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Pdf"}},"type":"object","required":["id","status","amount_paid","currency","created"],"title":"PaymentHistoryItem"},"PaymentHistoryResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/PaymentHistoryItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","required":["items"],"title":"PaymentHistoryResponse"},"PendingCommandItem":{"properties":{"id":{"type":"string","title":"Id"},"command_type":{"type":"string","title":"Command Type"},"payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload"}},"type":"object","required":["id","command_type"],"title":"PendingCommandItem"},"PendingPairResponse":{"properties":{"pair_code":{"type":"string","title":"Pair Code","description":"BCK-XXXX-XXXX pairing code"},"bot_name":{"type":"string","title":"Bot Name"},"bot_user_id":{"type":"string","title":"Bot User Id"},"expires_in":{"type":"integer","title":"Expires In","description":"Seconds until the code expires"}},"type":"object","required":["pair_code","bot_name","bot_user_id","expires_in"],"title":"PendingPairResponse"},"PhoneAvailabilityResponse":{"properties":{"available":{"type":"boolean","title":"Available"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["available","reason"],"title":"PhoneAvailabilityResponse"},"PortalResponse":{"properties":{"portal_url":{"type":"string","title":"Portal Url","description":"Stripe Customer Portal URL"}},"type":"object","required":["portal_url"],"title":"PortalResponse"},"PresignedUrlRequest":{"properties":{"document_url":{"type":"string","title":"Document Url","description":"Full S3 URL, s3:// URI, or key path of the document","example":"https://my-bucket.s3.amazonaws.com/verifications/alice/doc.pdf"},"expiration":{"type":"integer","title":"Expiration","description":"URL validity in seconds (60 – 604800)","default":3600,"example":3600}},"type":"object","required":["document_url"],"title":"PresignedUrlRequest","description":"Request body for admin presigned GET URL generation."},"PresignedUrlResponse":{"properties":{"presigned_url":{"type":"string","title":"Presigned Url","description":"Pre-signed S3 GET URL"},"expires_at":{"type":"string","title":"Expires At","description":"ISO 8601 expiry timestamp"},"bucket":{"type":"string","title":"Bucket","description":"S3 bucket name"},"key":{"type":"string","title":"Key","description":"S3 object key"}},"type":"object","required":["presigned_url","expires_at","bucket","key"],"title":"PresignedUrlResponse"},"ProfileOut":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"matrix_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Id"},"email":{"type":"string","format":"email","title":"Email"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"auto_destruct_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auto Destruct Time"},"account_verified":{"type":"boolean","title":"Account Verified"},"agreed_terms":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Agreed Terms"},"agreed_privacy":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Agreed Privacy"},"last_signed_in_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Signed In At"},"last_signed_out_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Signed Out At"},"deleted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deleted At"},"matrix_account_created":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Matrix Account Created"},"matrix_account_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Account Error"},"matrix_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Status"},"subscription_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Status"},"subscription_plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Plan"},"subscription_ends_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Subscription Ends At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["email","account_verified"],"title":"ProfileOut"},"ProfileUpdate":{"properties":{"username":{"type":"string","title":"Username","description":"Desired Matrix username (alphanumeric, min 5 chars)"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Full name"},"email":{"type":"string","format":"email","title":"Email"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Display name shown in Matrix"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Phone number in E.164 format","example":"+14155552671"},"auto_destruct_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auto Destruct Time","description":"Default message auto-destruct time","example":"7d"},"agreed_terms":{"type":"boolean","title":"Agreed Terms"},"agreed_privacy":{"type":"boolean","title":"Agreed Privacy"}},"type":"object","required":["username","email","agreed_terms","agreed_privacy"],"title":"ProfileUpdate"},"ProvisionBotRequest":{"properties":{"bot_name":{"type":"string","maxLength":255,"minLength":1,"title":"Bot Name","description":"Display name for the bot"},"bot_username":{"type":"string","maxLength":20,"minLength":4,"pattern":"^[a-z0-9_]+$","title":"Bot Username","description":"Lowercase alphanumeric username for the bot","example":"mybot"}},"type":"object","required":["bot_name","bot_username"],"title":"ProvisionBotRequest"},"ProvisionBotResponse":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"bot_user_id":{"type":"string","title":"Bot User Id","description":"Full Matrix user ID of the provisioned bot"},"status":{"type":"string","title":"Status","description":"Provisioning status","example":"provisioning"}},"type":"object","required":["bot_id","bot_user_id","status"],"title":"ProvisionBotResponse"},"ProvisionStatusResponse":{"properties":{"instance_id":{"type":"string","title":"Instance Id"},"orgo_computer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orgo Computer Id"},"provision_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provision Status"},"provision_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provision Detail"},"online":{"type":"boolean","title":"Online"}},"type":"object","required":["instance_id","orgo_computer_id","provision_status","online"],"title":"ProvisionStatusResponse"},"PushDeviceRegistration":{"properties":{"device_token":{"type":"string","title":"Device Token","description":"Device push token from APNs or FCM"},"environment":{"type":"string","title":"Environment","description":"Push environment: 'sandbox' or 'production'","default":"production","example":"production"},"platform":{"type":"string","title":"Platform","description":"Device platform: 'ios' or 'android'","example":"ios"},"device_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Name","description":"Human-readable device name","example":"iPhone 15 Pro"},"app_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"App Version","description":"Installed app version","example":"2.1.0"}},"type":"object","required":["device_token","platform"],"title":"PushDeviceRegistration","description":"Register a device token for push notifications."},"PushDeviceResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"environment":{"type":"string","title":"Environment"},"app_id":{"type":"string","title":"App Id"},"device_token_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Device Token Id"}},"type":"object","required":["success","message","environment","app_id"],"title":"PushDeviceResponse"},"PushEnvironmentResponse":{"properties":{"user_id":{"type":"integer","title":"User Id"},"matrix_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matrix Id"},"environment":{"type":"string","title":"Environment"},"app_id":{"type":"string","title":"App Id"},"active_devices":{"type":"integer","title":"Active Devices"}},"type":"object","required":["user_id","environment","app_id","active_devices"],"title":"PushEnvironmentResponse"},"PushHealthResponse":{"properties":{"status":{"type":"string","title":"Status"},"sygnal_accessible":{"type":"boolean","title":"Sygnal Accessible"},"sygnal_url":{"type":"string","title":"Sygnal Url"},"timestamp":{"type":"string","title":"Timestamp"}},"type":"object","required":["status","sygnal_accessible","sygnal_url","timestamp"],"title":"PushHealthResponse"},"RecoveryKeyExistsResponse":{"properties":{"exists":{"type":"boolean","title":"Exists"}},"type":"object","required":["exists"],"title":"RecoveryKeyExistsResponse"},"RecoveryKeyResponse":{"properties":{"recovery_key":{"type":"string","title":"Recovery Key"},"created_at":{"type":"string","title":"Created At"},"created_by_device":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Device"}},"type":"object","required":["recovery_key","created_at"],"title":"RecoveryKeyResponse"},"RecoveryKeyStoredResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"RecoveryKeyStoredResponse"},"RedeemPairingRequest":{"properties":{"code":{"type":"string","title":"Code","description":"Pairing code from the iOS app (BCK-XXXX-XXXX format)","example":"BCK-A1B2-C3D4"},"instance_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Instance Id","description":"Globally unique OpenClaw instance identifier. Required as of the strict 1:1 owner-to-instance change — must already be registered and owned by the bot owner.","example":"openclaw-mac-c24c46bcd78c5642"},"machine_fingerprint":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Machine Fingerprint","description":"Deterministic per-machine fingerprint (sha256(hostname-platform-arch)[:16]). Sent for symmetry with /openclaw/register; the redeem endpoint currently ignores it but plugin clients populate it for forward compatibility — future server-side abuse detection or pair-time reconciliation can rely on it without another plugin release."}},"type":"object","required":["code"],"title":"RedeemPairingRequest"},"RedeemPairingResponse":{"properties":{"homeserver":{"type":"string","title":"Homeserver","description":"Matrix homeserver URL"},"access_token":{"type":"string","title":"Access Token","description":"Bot Matrix access token"},"user_id":{"type":"string","title":"User Id","description":"Bot Matrix user ID"},"bot_name":{"type":"string","title":"Bot Name"},"device_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Id"},"bot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bot Id","description":"Bot's primary key UUID. The Hermes runtime CLI uses this to call back into /hermes/bots/<id>/runtime-bootstrap once it captures the cross-signing recovery key from container logs. Optional for backwards compatibility — older CLIs that don't know this field skip the bootstrap and rely on the daemon's per-beat verifier to do it later."},"runtime":{"type":"string","title":"Runtime","description":"Per-bot runtime the CLI should spin up: 'openclaw' uses the existing plugin config write; 'hermes' triggers the local Hermes container provisioner. Older CLIs that don't know this field default to OpenClaw behaviour.","default":"openclaw"},"owner_matrix_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Matrix User Id","description":"Matrix user id of the bot owner. The Hermes runtime wires this into MATRIX_ALLOWED_USERS so the new bot bypasses the pair-code flow for its owner (per J1 in the strategy doc). Returned only for hermes-runtime bots."}},"type":"object","required":["homeserver","access_token","user_id","bot_name"],"title":"RedeemPairingResponse"},"RedisHealthResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"redis":{"type":"string","title":"Redis"}},"type":"object","required":["ok","redis"],"title":"RedisHealthResponse"},"RefreshMatrixTokenRequest":{"properties":{"device_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Id","description":"Existing device ID to preserve E2EE state"}},"type":"object","title":"RefreshMatrixTokenRequest"},"RefreshMatrixTokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token"},"device_id":{"type":"string","title":"Device Id"},"homeserver":{"type":"string","title":"Homeserver"},"user_id":{"type":"string","title":"User Id"}},"type":"object","required":["access_token","device_id","homeserver","user_id"],"title":"RefreshMatrixTokenResponse"},"RefreshTokenRequest":{"properties":{"refresh_token":{"type":"string","title":"Refresh Token"},"email":{"type":"string","format":"email","title":"Email"},"session_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Session Id"},"cognito_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cognito Username","description":"Immutable Cognito username (sub UUID) if known"}},"type":"object","required":["refresh_token","email"],"title":"RefreshTokenRequest"},"RefreshTokenResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"access_token":{"type":"string","title":"Access Token"},"id_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id Token"},"expires_in":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires In"},"token_type":{"type":"string","title":"Token Type","default":"Bearer"}},"type":"object","required":["success","access_token"],"title":"RefreshTokenResponse"},"RegisterInstanceRequest":{"properties":{"instance_id":{"type":"string","maxLength":255,"minLength":1,"title":"Instance Id","description":"Unique instance identifier"},"label":{"type":"string","maxLength":255,"minLength":1,"title":"Label","description":"Human-readable machine label","example":"my-macbook"},"version":{"type":"string","maxLength":50,"minLength":1,"title":"Version","description":"OpenClaw version","example":"1.2.3"},"online":{"type":"boolean","title":"Online","description":"Whether the instance is online","default":true},"machine_fingerprint":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Machine Fingerprint","description":"Stable per-machine fingerprint (host-platform-arch hash)"},"provider":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Provider","description":"Host provider: 'orgo', 'local', etc."},"orgo_workspace_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Orgo Workspace Id"},"orgo_workspace_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Orgo Workspace Name"},"orgo_computer_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Orgo Computer Id"}},"type":"object","required":["instance_id","label","version"],"title":"RegisterInstanceRequest"},"RepairResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"message":{"type":"string","title":"Message"},"command_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Command Id"}},"type":"object","required":["ok","message"],"title":"RepairResponse"},"RepairedBot":{"properties":{"bot_id":{"type":"string","title":"Bot Id"},"bot_user_id":{"type":"string","title":"Bot User Id"},"pair_code":{"type":"string","title":"Pair Code"},"expires_in":{"type":"integer","title":"Expires In"}},"type":"object","required":["bot_id","bot_user_id","pair_code","expires_in"],"title":"RepairedBot","description":"Credentials minted for a bot that was just reactivated. Returned so\nthe iOS client can surface the pairing code as a manual-entry fallback\nwhen the plugin's auto-pair handler doesn't pick up the broadcast."},"ResendCodeRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"ResendCodeRequest"},"ResendCodeResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"ResendCodeResponse"},"ResetPasswordRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"code":{"type":"string","maxLength":6,"minLength":6,"title":"Code"},"new_password":{"type":"string","minLength":8,"title":"New Password"}},"type":"object","required":["email","code","new_password"],"title":"ResetPasswordRequest"},"ResetPasswordResponse":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"ResetPasswordResponse"},"ResolveDowngradeRequest":{"properties":{"feature":{"type":"string","title":"Feature","description":"Which gate this keep-set applies to. Must be a pick-N feature.","default":"multiple_openclaw_instances"},"keep_ids":{"items":{"type":"string"},"type":"array","title":"Keep Ids","description":"IDs from that feature's DowngradeItem.id that the user wants to keep. Anything NOT in this set gets disabled."}},"type":"object","title":"ResolveDowngradeRequest"},"ResolveDowngradeResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"resolved_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Resolved At"},"resolution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution"},"feature":{"type":"string","title":"Feature"},"kept":{"items":{"type":"string"},"type":"array","title":"Kept"},"disabled":{"items":{"type":"string"},"type":"array","title":"Disabled"},"remaining_features_over_cap":{"items":{"type":"string"},"type":"array","title":"Remaining Features Over Cap"}},"type":"object","required":["request_id","feature","kept","disabled","remaining_features_over_cap"],"title":"ResolveDowngradeResponse"},"ResolveUpgradeRequest":{"properties":{"feature":{"type":"string","title":"Feature"},"reenable_ids":{"items":{"type":"string"},"type":"array","title":"Reenable Ids"}},"type":"object","required":["feature"],"title":"ResolveUpgradeRequest"},"ResolveUpgradeResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"resolved_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Resolved At"},"resolution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution"},"feature":{"type":"string","title":"Feature"},"reenabled":{"items":{"type":"string"},"type":"array","title":"Reenabled"},"remaining_features_with_parked":{"items":{"type":"string"},"type":"array","title":"Remaining Features With Parked"},"repaired_bots":{"items":{"$ref":"#/components/schemas/RepairedBot"},"type":"array","title":"Repaired Bots"}},"type":"object","required":["request_id","feature","reenabled","remaining_features_with_parked"],"title":"ResolveUpgradeResponse"},"RoomCleanupResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Deleted"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["success"],"title":"RoomCleanupResponse"},"RoomInfoResponse":{"properties":{"room_id":{"type":"string","title":"Room Id"},"members":{"items":{},"type":"array","title":"Members"},"bots":{"items":{},"type":"array","title":"Bots"},"humans":{"items":{},"type":"array","title":"Humans"}},"type":"object","required":["room_id","members","bots","humans"],"title":"RoomInfoResponse"},"RootResponse":{"properties":{"message":{"type":"string","title":"Message"},"status":{"type":"string","title":"Status"},"timestamp":{"type":"string","title":"Timestamp"}},"type":"object","required":["message","status","timestamp"],"title":"RootResponse"},"RotateTokenRequest":{"properties":{},"type":"object","title":"RotateTokenRequest","description":"Rotate has no body — we preserve name/expires_in/binding from the old\ntoken. A request body is accepted (but currently ignored) so the endpoint\ncan grow options later without breaking callers."},"SelfDeactivateRequest":{"properties":{"password":{"type":"string","minLength":1,"title":"Password"}},"type":"object","required":["password"],"title":"SelfDeactivateRequest"},"SessionListResponse":{"properties":{"sessions":{"items":{"$ref":"#/components/schemas/UserSessionOut"},"type":"array","title":"Sessions"}},"type":"object","required":["sessions"],"title":"SessionListResponse"},"ShareDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"ShareDeleteResponse"},"ShareResponse":{"properties":{"id":{"type":"integer","title":"Id"},"bot_id":{"type":"string","title":"Bot Id"},"shared_with_user_id":{"type":"string","title":"Shared With User Id"},"shared_with_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shared With Display Name"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["id","bot_id","shared_with_user_id","created_at"],"title":"ShareResponse"},"SharedBotResponse":{"properties":{"share_id":{"type":"integer","title":"Share Id"},"bot_id":{"type":"string","title":"Bot Id"},"bot_name":{"type":"string","title":"Bot Name"},"bot_user_id":{"type":"string","title":"Bot User Id"},"owner_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Display Name"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["share_id","bot_id","bot_name","bot_user_id","created_at"],"title":"SharedBotResponse"},"SharingToggleRequest":{"properties":{"enabled":{"type":"boolean","title":"Enabled","description":"Enable or disable sharing for this bot"}},"type":"object","required":["enabled"],"title":"SharingToggleRequest"},"SignupRequest":{"properties":{"name":{"type":"string","minLength":1,"title":"Name"},"email":{"type":"string","format":"email","title":"Email"},"username":{"type":"string","minLength":5,"pattern":"^[A-Za-z0-9]+$","title":"Username"},"password":{"type":"string","minLength":8,"title":"Password"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Phone number in E.164 format"},"device_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Token","description":"Apple DeviceCheck token (base64). When present, the server queries Apple's DeviceCheck API for bit0 and rejects signup if a trial has already been used on this device. Missing token is treated as no signal (e.g. simulator, unsupported device) and signup proceeds without the trial-abuse gate."}},"type":"object","required":["name","email","username","password"],"title":"SignupRequest"},"SignupResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"user_sub":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Sub","description":"Cognito user sub (UUID)"},"matrix_account_created":{"type":"boolean","title":"Matrix Account Created","description":"Whether Matrix account was created","default":false}},"type":"object","required":["success","message"],"title":"SignupResponse"},"SignupVerifyRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"code":{"type":"string","maxLength":6,"minLength":6,"title":"Code"}},"type":"object","required":["email","code"],"title":"SignupVerifyRequest"},"SignupVerifyResponse":{"properties":{"verified":{"type":"boolean","title":"Verified"},"message":{"type":"string","title":"Message"}},"type":"object","required":["verified","message"],"title":"SignupVerifyResponse"},"SkillInstallRequest":{"properties":{"skill_name":{"type":"string","title":"Skill Name"},"target_instance_id":{"type":"string","title":"Target Instance Id"}},"type":"object","required":["skill_name","target_instance_id"],"title":"SkillInstallRequest"},"SkillMachineInfo":{"properties":{"instanceId":{"type":"string","title":"Instanceid"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hostname"}},"type":"object","required":["instanceId"],"title":"SkillMachineInfo"},"SkillSummary":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"source":{"type":"string","title":"Source","default":"auto"},"useCount":{"type":"integer","title":"Usecount","default":0},"confirmed":{"type":"boolean","title":"Confirmed","default":false},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Createdat"},"installedOn":{"anyOf":[{"items":{"$ref":"#/components/schemas/SkillMachineInfo"},"type":"array"},{"type":"null"}],"title":"Installedon"}},"type":"object","required":["name","description"],"title":"SkillSummary"},"StoreRecoveryKeyRequest":{"properties":{"recovery_key":{"type":"string","title":"Recovery Key","description":"Recovery key generated by iOS Matrix SDK"},"device_id":{"type":"string","title":"Device Id","description":"Device ID that generated the key"}},"type":"object","required":["recovery_key","device_id"],"title":"StoreRecoveryKeyRequest"},"SubscriptionStatusResponse":{"properties":{"subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Id"},"status":{"type":"string","title":"Status","description":"Subscription status","example":"active"},"subscription_status":{"type":"string","title":"Subscription Status"},"subscription_price_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Price Id"},"subscription_ends_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Ends At"},"stripe_customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Customer Id"},"plan_name":{"type":"string","title":"Plan Name"},"is_free":{"type":"boolean","title":"Is Free"},"is_canceling":{"type":"boolean","title":"Is Canceling","default":false},"can_cancel":{"type":"boolean","title":"Can Cancel","default":false},"pending_plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pending Plan Name"},"pending_change_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pending Change Date"},"can_change_plan":{"type":"boolean","title":"Can Change Plan","default":false}},"type":"object","required":["status","subscription_status","plan_name","is_free"],"title":"SubscriptionStatusResponse"},"SupportedVersionOut":{"properties":{"component":{"type":"string","title":"Component"},"version":{"type":"string","title":"Version"},"min_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Min Version"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By"},"latest_npm_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Npm Version"},"latest_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Checked At"}},"type":"object","required":["component","version"],"title":"SupportedVersionOut"},"SupportedVersionUpdateRequest":{"properties":{"component":{"type":"string","title":"Component"},"version":{"type":"string","title":"Version"},"min_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Min Version"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["component","version"],"title":"SupportedVersionUpdateRequest"},"SupportedVersionUpdateResponse":{"properties":{"component":{"type":"string","title":"Component"},"version":{"type":"string","title":"Version"},"previous_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Previous Version"},"min_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Min Version"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By"}},"type":"object","required":["component","version","previous_version"],"title":"SupportedVersionUpdateResponse"},"TestNotificationResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"}},"type":"object","required":["success","message"],"title":"TestNotificationResponse"},"TokenIntrospectResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"token_prefix":{"type":"string","title":"Token Prefix"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"},"bound_instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bound Instance Id"},"bound_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Bound At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"last_used_ip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used Ip"},"use_count":{"type":"integer","title":"Use Count"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"status":{"type":"string","title":"Status","description":"One of: active | bound | expired | revoked."},"recent_audit":{"items":{"$ref":"#/components/schemas/AuditEventItem"},"type":"array","title":"Recent Audit"}},"type":"object","required":["id","name","token_prefix","created_at","use_count","scopes","status"],"title":"TokenIntrospectResponse","description":"Full-token view, including the most recent audit events."},"TokenListItem":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"token_prefix":{"type":"string","title":"Token Prefix"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"},"bound_instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bound Instance Id"},"bound_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Bound At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"last_used_ip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used Ip"},"use_count":{"type":"integer","title":"Use Count"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"status":{"type":"string","title":"Status","description":"One of: active | bound | expired | revoked."}},"type":"object","required":["id","name","token_prefix","created_at","use_count","scopes","status"],"title":"TokenListItem","description":"Metadata-only view of a token. Never includes plaintext or hash."},"TrackMediaRequest":{"properties":{"size_bytes":{"type":"integer","exclusiveMinimum":0.0,"title":"Size Bytes","description":"Actual size of the uploaded file in bytes"}},"type":"object","required":["size_bytes"],"title":"TrackMediaRequest"},"TrialStatusResponse":{"properties":{"trial_active":{"type":"boolean","title":"Trial Active"},"trial_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trial Expires At"},"has_active_subscription":{"type":"boolean","title":"Has Active Subscription"},"plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Name"},"plan_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Display Name"},"billing_interval":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Interval"},"subscription_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Source"},"subscription_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Status"},"pending_plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pending Plan Name"},"pending_change_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pending Change Date"}},"type":"object","required":["trial_active","has_active_subscription"],"title":"TrialStatusResponse"},"UnbindTokenResponse":{"properties":{"id":{"type":"string","title":"Id"},"bound_instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bound Instance Id"},"bound_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Bound At"}},"type":"object","required":["id"],"title":"UnbindTokenResponse"},"UpdateBotRequest":{"properties":{"bot_name":{"type":"string","maxLength":255,"minLength":1,"title":"Bot Name","description":"New display name for the bot"}},"type":"object","required":["bot_name"],"title":"UpdateBotRequest"},"UpdateBotRoomModeRequest":{"properties":{"mode":{"type":"string","pattern":"^(auto|mention)$","title":"Mode","description":"Response mode: 'auto' (reply to all) or 'mention' (reply only when @mentioned)"}},"type":"object","required":["mode"],"title":"UpdateBotRoomModeRequest"},"UpdateBugReportRequest":{"properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"open | in_progress | resolved | closed"},"admin_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Admin Notes"}},"type":"object","title":"UpdateBugReportRequest"},"UpdateRecoveryKeyRequest":{"properties":{"recovery_key":{"type":"string","title":"Recovery Key","description":"New recovery key"},"device_id":{"type":"string","title":"Device Id","description":"Device ID that generated the key"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason for update"}},"type":"object","required":["recovery_key","device_id"],"title":"UpdateRecoveryKeyRequest"},"UpgradeFeatureState":{"properties":{"feature":{"type":"string","title":"Feature"},"new_limit":{"type":"integer","title":"New Limit"},"currently_active":{"type":"integer","title":"Currently Active"},"parked_items":{"items":{"$ref":"#/components/schemas/UpgradeItem"},"type":"array","title":"Parked Items"},"resolved":{"type":"boolean","title":"Resolved"}},"type":"object","required":["feature","new_limit","currently_active","parked_items","resolved"],"title":"UpgradeFeatureState"},"UpgradeItem":{"properties":{"id":{"type":"string","title":"Id"},"kind":{"type":"string","title":"Kind"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"parked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Parked At"},"instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Id"},"bot_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bot User Id"}},"type":"object","required":["id","kind"],"title":"UpgradeItem"},"UploadUrlResponse":{"properties":{"upload_url":{"type":"string","title":"Upload Url","description":"Pre-signed S3 PUT URL"},"file_url":{"type":"string","title":"File Url","description":"Public S3 file URL (after upload)"},"max_bytes":{"type":"integer","title":"Max Bytes","description":"Maximum allowed file size in bytes","example":20971520}},"type":"object","required":["upload_url","file_url","max_bytes"],"title":"UploadUrlResponse","description":"Response from GET /upload-url."},"UserProfileInLogin":{"properties":{"id":{"type":"integer","title":"Id"},"email":{"type":"string","title":"Email"},"name":{"type":"string","title":"Name"},"username":{"type":"string","title":"Username"},"matrix_id":{"type":"string","title":"Matrix Id"},"display_name":{"type":"string","title":"Display Name"},"account_verified":{"type":"boolean","title":"Account Verified"}},"type":"object","required":["id","email","name","username","matrix_id","display_name","account_verified"],"title":"UserProfileInLogin"},"UserSessionOut":{"properties":{"id":{"type":"integer","title":"Id"},"device_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device Name"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At"}},"type":"object","required":["id","created_at","last_seen_at"],"title":"UserSessionOut"},"UsernameCheckResponse":{"properties":{"valid":{"type":"boolean","title":"Valid"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["valid"],"title":"UsernameCheckResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VersionCheckRequest":{"properties":{"platform":{"type":"string","title":"Platform","description":"Platform: 'ios' or 'android'","example":"ios"},"version":{"type":"string","title":"Version","description":"Current app version","example":"1.2.3"},"build_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Build Number","description":"Build number (optional)","example":456}},"type":"object","required":["platform","version"],"title":"VersionCheckRequest"},"VersionCheckResponse":{"properties":{"current_version":{"type":"string","title":"Current Version"},"min_version":{"type":"string","title":"Min Version"},"latest_version":{"type":"string","title":"Latest Version"},"is_update_required":{"type":"boolean","title":"Is Update Required"},"is_force_update":{"type":"boolean","title":"Is Force Update"},"is_maintenance_mode":{"type":"boolean","title":"Is Maintenance Mode"},"release_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Release Notes"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["current_version","min_version","latest_version","is_update_required","is_force_update","is_maintenance_mode"],"title":"VersionCheckResponse"},"VersionCreateRequest":{"properties":{"platform":{"type":"string","title":"Platform","description":"Platform: 'ios' or 'android'"},"version":{"type":"string","title":"Version","description":"Version number","example":"1.2.3"},"build_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Build Number","description":"Build number"},"min_version":{"type":"string","title":"Min Version","description":"Minimum required version"},"is_force_update":{"type":"boolean","title":"Is Force Update","description":"Force update required","default":false},"is_maintenance_mode":{"type":"boolean","title":"Is Maintenance Mode","description":"Maintenance mode active","default":false},"release_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Release Notes","description":"Release notes"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url","description":"Download URL"}},"type":"object","required":["platform","version","min_version"],"title":"VersionCreateRequest"},"VersionDeleteResponse":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"VersionDeleteResponse"},"VersionResponse":{"properties":{"id":{"type":"integer","title":"Id"},"platform":{"type":"string","title":"Platform"},"version":{"type":"string","title":"Version"},"build_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Build Number"},"min_version":{"type":"string","title":"Min Version"},"is_force_update":{"type":"boolean","title":"Is Force Update"},"is_maintenance_mode":{"type":"boolean","title":"Is Maintenance Mode"},"release_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Release Notes"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","platform","version","min_version","is_force_update","is_maintenance_mode","created_at","updated_at"],"title":"VersionResponse"},"VersionUpdateRequest":{"properties":{"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"New version number"},"build_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Build Number","description":"New build number"},"min_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Min Version","description":"New minimum required version"},"is_force_update":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Force Update","description":"Force update flag"},"is_maintenance_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Maintenance Mode","description":"Maintenance mode flag"},"release_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Release Notes","description":"Release notes"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url","description":"Download URL"}},"type":"object","title":"VersionUpdateRequest"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}