{ "openapi": "3.1.0", "info": { "title": "Hello by Flow API", "description": "The Hello by Flow API powers a multi-tenant cloud calling SaaS platform: external Twilio\nvoice & SMS, free internal Team Chat, peer-to-peer WebRTC meetings, agent dashboards,\nand a platform-owner console for managing customer organizations.\n\n## Authentication\n\nTwo equivalent auth schemes are supported on every protected endpoint:\n\n| Scheme | How |\n|---|---|\n| **`access_token` cookie** | Set automatically by `POST /api/auth/login`. Sent with every same-site request. |\n| **`Authorization: Bearer `** | Use the `access_token` field returned by `/auth/login` (12-hour TTL). |\n\nThe token encodes the user id and role; org scoping is enforced server-side via\nthe `org_scope(user)` helper in `middleware/auth.py`.\n\n## Roles\n\n| Role | Visibility |\n|---|---|\n| `owner` | Cross-org \u2014 runs `/api/owner/*` platform console. |\n| `admin` | Full control of own organization. |\n| `supervisor` | Read-only across org (calls, recordings, analytics). |\n| `agent` | Only their own contacts / calls / SMS. |\n\n## Errors\n\nAll errors use the FastAPI default `{ \"detail\": \"...\" }` envelope. Status codes follow\nHTTP semantics: 400 (validation), 401 (no auth), 403 (wrong role), 404 (not found / not\nvisible), 429 (lockout), 503 (Twilio/LLM down). See per-endpoint `responses` for the\nexact failure modes.\n\n## Multi-tenancy\n\nEvery persisted document carries an `org_id`. Non-owner queries are automatically\nscoped to the caller's org. Agent-role users see only their own rows.", "contact": { "name": "Hello by Flow Partner Support", "url": "https://hellobyflow.com/developers", "email": "partners@hellobyflow.com" }, "license": { "name": "Proprietary \u2014 Hello by Flow Cloud Inc." }, "version": "1.0.0" }, "paths": { "/api/auth/csrf": { "get": { "tags": [ "Auth" ], "summary": "Bootstrap a CSRF token (sets `csrf_token` cookie)", "description": "Call this once before any unsafe (POST/PATCH/DELETE/PUT) request. The response sets a JS-readable `csrf_token` cookie that the frontend must echo back as the `X-CSRF-Token` header on subsequent unsafe calls. The token rotates every 90 days; reading the cookie does not consume it.", "operationId": "csrf_bootstrap_api_auth_csrf_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [] } }, "/api/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Disabled \u2014 use POST /api/signup instead", "operationId": "register_disabled_api_auth_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Sign in with email/username + password", "description": "Returns the authenticated user. Sets HttpOnly `access_token` (15 min) and `refresh_token` (90 d) cookies plus a JS-readable `csrf_token` cookie. After 5 failed attempts the identifier is locked for 15 minutes.", "operationId": "login_api_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "429": { "description": "Rate-limited (e.g. login brute-force lockout).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many failed attempts. Try again in 15 minutes." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Rotate the refresh token (returns new access cookie)", "description": "Reads the `refresh_token` HttpOnly cookie, validates it against the server-side store, and ROTATES it: the old refresh is revoked, a new refresh + new access are issued as cookies. Replay of an already-rotated token revokes the entire token family and forces re-login.", "operationId": "refresh_api_auth_refresh_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } }, "security": [] } }, "/api/auth/forgot-password": { "post": { "tags": [ "Auth" ], "summary": "Send a password reset link to owner / admin accounts", "description": "Accepts {email}. If an eligible account exists (role in {owner, admin} and not disabled), a signed reset link is emailed with a 30-minute expiry. Always returns 200 with a generic message \u2014 no user enumeration. Rate-limited per email + client IP.", "operationId": "forgot_password_api_auth_forgot_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Rate-limited (e.g. login brute-force lockout).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many failed attempts. Try again in 15 minutes." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/auth/reset-password": { "post": { "tags": [ "Auth" ], "summary": "Consume a password reset token and set a new password", "description": "Accepts {token, new_password}. Verifies the signed reset token and the server-side single-use row, sets the new bcrypt hash, bumps the user's session_epoch (invalidating all prior sessions) and marks the reset row consumed. On success the user must sign in again.", "operationId": "reset_password_api_auth_reset_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/auth/change-password": { "post": { "tags": [ "Auth" ], "summary": "Change the current user's password", "description": "Verifies the current password, sets the new one, clears any `must_change_password` flag, revokes every other session (session epoch bump) and re-mints fresh cookies for this device.", "operationId": "change_password_api_auth_change_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Sign out the current session (revokes the active refresh token)", "description": "Revokes only the current device's refresh token. Use /auth/sessions/revoke-all to sign out everywhere.", "operationId": "logout_api_auth_logout_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/auth/ws-ticket": { "post": { "tags": [ "Auth" ], "summary": "Mint a short-lived WebSocket auth ticket (60-second TTL)", "description": "WebSockets cannot easily carry HttpOnly cookies across all browsers/proxies, so we expose a one-shot ticket: POST here (cookies + CSRF) and use the returned `ticket` as the `?ticket=\u2026` query param on the RTC WS URL. The ticket is a signed JWT with `type=ws` and a 60s lifetime; the WS handler validates it like any other JWT but rejects non-`ws` types.", "operationId": "ws_ticket_api_auth_ws_ticket_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Get the current authenticated user", "operationId": "me_api_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/auth/otp/verify": { "post": { "tags": [ "Auth" ], "summary": "Email OTP \u2014 verify the 6-digit code emailed to the user", "description": "Called with the `challenge_token` returned from /auth/login when the server responded `email_otp_challenge=true`. Accepts a 6-digit code from the user's inbox. On success, mints auth cookies. Set `trust_device=true` to skip OTP on this browser for 30 days.", "operationId": "otp_verify_api_auth_otp_verify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpVerifyReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/auth/otp/resend": { "post": { "tags": [ "Auth" ], "summary": "Email OTP \u2014 resend the verification code (30-second cool-down)", "description": "Issues a fresh 6-digit OTP and re-emails it. Rate-limited to once every 30 seconds per challenge; further calls return 429 with `Retry-After` and the remaining seconds in the error detail.", "operationId": "otp_resend_api_auth_otp_resend_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpResendReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "429": { "description": "Too many resend requests" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/auth/otp/status": { "get": { "tags": [ "Auth" ], "summary": "Email OTP \u2014 return whether OTP is required for the current user", "operationId": "otp_status_api_auth_otp_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/auth/otp/devices": { "get": { "tags": [ "Auth" ], "summary": "Email OTP \u2014 list this user's trusted devices", "operationId": "otp_devices_api_auth_otp_devices_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } } }, "delete": { "tags": [ "Auth" ], "summary": "Email OTP \u2014 revoke ALL trusted devices for the current user", "operationId": "otp_devices_revoke_all_api_auth_otp_devices_delete", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/auth/sessions": { "get": { "tags": [ "Auth" ], "summary": "List the caller's active sessions across devices", "description": "Returns one entry per active refresh-token. The current device is marked `current: true` (matched by jti).", "operationId": "my_sessions_api_auth_sessions_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/auth/sessions/{session_id}": { "delete": { "tags": [ "Auth" ], "summary": "Revoke a specific session (the device behind that jti will be signed out on next API call)", "operationId": "revoke_session_api_auth_sessions__session_id__delete", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/auth/sessions/revoke-all": { "post": { "tags": [ "Auth" ], "summary": "Revoke ALL of the caller's sessions (logout everywhere)", "operationId": "revoke_all_api_auth_sessions_revoke_all_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } } } } }, "/api/me": { "patch": { "tags": [ "Auth" ], "summary": "Update the current user's profile", "operationId": "update_me_api_me_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdateReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/onboarding/intent": { "post": { "tags": [ "Business" ], "summary": "Phase-2 signup: create the signup intent (pre-payment)", "description": "Creates an `organizations` row in `status=\"intent\"`. Middleware blocks all product access until the intent is finalised by a successful Stripe payment (and KYC, if required). Legacy `POST /api/signup` remains available under `NEW_SIGNUP_FUNNEL_ENABLED=false`.", "operationId": "onboarding_create_intent_api_onboarding_intent_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingIntentIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingIntentOut" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/onboarding/intent/{intent_id}": { "get": { "tags": [ "Business" ], "summary": "Phase-2 signup: poll intent state", "operationId": "onboarding_intent_status_api_onboarding_intent__intent_id__get", "parameters": [ { "name": "intent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Intent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingStatusOut" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/onboarding/intent/{intent_id}/kyc": { "post": { "tags": [ "Business" ], "summary": "Phase-2 signup: start KYC (Persona/Stripe Identity)", "description": "Creates a verification session with the currently-active identity provider (per Owner Settings). Business rule: KYC must complete BEFORE the Stripe Checkout endpoint below will authorise payment.", "operationId": "onboarding_intent_start_kyc_api_onboarding_intent__intent_id__kyc_post", "parameters": [ { "name": "intent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Intent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingKycStartOut" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/onboarding/intent/{intent_id}/checkout": { "post": { "tags": [ "Business" ], "summary": "Phase-2 signup: create Stripe Checkout session (blocks pre-KYC)", "description": "Creates a hosted Stripe Checkout Session. **Explicitly blocks if KYC is required and not yet verified** \u2014 this is the KYC-before-payment gate mandated by the redesign. Metadata `hbf_intent_id` lets the `checkout.session.completed` webhook route the payment back to the intent org and trigger `finalize_intent()`.", "operationId": "onboarding_intent_checkout_api_onboarding_intent__intent_id__checkout_post", "parameters": [ { "name": "intent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Intent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingCheckoutIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingCheckoutOut" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/api/onboarding/seats": { "get": { "tags": [ "Business" ], "summary": "Phase-3 wizard: list this org's Communication Seats + their lifecycle", "description": "Returns every `virtual_numbers` row belonging to the admin's org.\n\nThe rows carry the extension-first Communication Seat identity: id,\nseat_number, lifecycle_state, and (if bound) phone_e164 and assigned user.", "operationId": "onboarding_list_seats_api_onboarding_seats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatsListOut" } } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/onboarding/seats/{seat_id}/bind-number": { "post": { "tags": [ "Business" ], "summary": "Phase-3 wizard: bind a selected Twilio number to a purchased seat", "description": "Purchases the specified Twilio number and permanently attaches it to the given seat. Idempotent \u2014 once a seat has a bound number, the endpoint returns HTTP 400. Uses the existing Twilio provider primitive.", "operationId": "onboarding_bind_number_api_onboarding_seats__seat_id__bind_number_post", "parameters": [ { "name": "seat_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Seat Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatBindNumberIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatBindNumberOut" } } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/onboarding/seats/{seat_id}/assign-user": { "post": { "tags": [ "Business" ], "summary": "Phase-3 wizard: create a user and permanently assign to a seat", "description": "Creates a new employee user record and attaches them to the specified seat. Seat lifecycle transitions `number_assigned \u2192 active` (or `vacant \u2192 active` on re-assignment). Employees never own their identity \u2014 the org admin sets the username & password here.", "operationId": "onboarding_assign_user_to_seat_api_onboarding_seats__seat_id__assign_user_post", "parameters": [ { "name": "seat_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Seat Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatAssignUserIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatAssignUserOut" } } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/auth/upgrade-to-business": { "post": { "tags": [ "Business" ], "summary": "Upgrade a solo workspace to a multi-seat business org", "description": "Renames the org, switches `type` from `individual` to `business`, and promotes the caller to `admin` so they can invite teammates. Returns the updated org.", "operationId": "upgrade_to_business_api_auth_upgrade_to_business_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeBusinessReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Contact not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/token": { "get": { "tags": [ "Business" ], "summary": "Mint a Voice SDK access token", "description": "Returns a short-lived (1 hour) JWT the browser uses to register a Twilio Voice softphone. Identity is `vocalis_{username|user_id}` so inbound `dial.client()` rings the right agent.", "operationId": "twilio_access_token_api_twilio_token_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } } } } }, "/api/twilio/account-status": { "get": { "tags": [ "Business" ], "summary": "Twilio account info (Trial vs Full, verified callers)", "description": "Returns the upstream Twilio account type/status, the list of verified outbound caller IDs, and any recently rejected inbound callers (so admins know which numbers to verify on Trial accounts).", "operationId": "twilio_account_status_api_twilio_account_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/twilio/client-event": { "post": { "tags": [ "Business" ], "summary": "Persist a Twilio Voice SDK browser event for diagnostics", "description": "Diagnostics-only. Frontend fires a small beacon for every Twilio Device / Call event (registered, unregistered, accept, disconnect, cancel, error) so a support engineer can correlate the browser SDK timeline with the /twilio/status backend callback and the CallSid on the Twilio Console. Zero effect on call routing / behaviour.", "operationId": "twilio_client_event_api_twilio_client_event_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/twilio/call-timeline/{call_sid}": { "get": { "tags": [ "Business" ], "summary": "Correlated timeline for a Twilio CallSid", "description": "Returns everything we know about one call in a single view: the call row from Twilio itself, our /twilio/status callback snapshot, every browser SDK event we received, and any Twilio Notification records (SIP codes, error text). Use this instead of clicking through the Twilio Console when investigating 31005 / dropped calls.", "operationId": "twilio_call_timeline_api_twilio_call_timeline__call_sid__get", "parameters": [ { "name": "call_sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Sid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/webhook-health": { "get": { "tags": [ "Business" ], "summary": "Twilio webhook URLs current state", "description": "Shows the Voice/SMS/Status URLs that Twilio currently has on record for your TwiML App and each purchased number, side-by-side with what our backend expects. Any mismatch is a probable cause of call/SMS failures (Twilio error 31005, silent-drop, missing inbound recordings).", "operationId": "twilio_webhook_health_api_twilio_webhook_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } } } } }, "/api/twilio/credentials-audit": { "get": { "tags": [ "Business" ], "summary": "Twilio credential-source drift audit", "description": "iter140 diagnostic: reports the last 4 chars of the Twilio Account SID at each of the three credential sources \u2014 env vars, `db.platform_settings.twilio`, and `db.provider_configs.twilio.voice/sms` \u2014 plus which one the production calling client actually loaded at boot. Use this when the Owner-Console health widget disagrees with real outbound calling (symptom: `HTTP 403 Test Account Credentials` while live calls work). Any mismatch here is the root cause.", "operationId": "twilio_credentials_audit_api_twilio_credentials_audit_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/twilio/reconcile-webhooks": { "post": { "tags": [ "Business" ], "summary": "Force-repoint Twilio TwiML App + numbers to this backend", "description": "One-click reconciliation for admins hitting Twilio error 31005 or silent call drops. Re-writes the Voice / SMS / Status URLs on your TwiML App AND every purchased number to point at this backend's `REACT_APP_BACKEND_URL`. Idempotent \u2014 safe to run any time.", "operationId": "twilio_reconcile_webhooks_api_twilio_reconcile_webhooks_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } } } } }, "/api/twilio/recent-calls": { "get": { "tags": [ "Business" ], "summary": "Recent Twilio call attempts with error codes", "description": "Reads the last 20 calls straight from Twilio's API. For each call, returns the direction, status, and \u2014 critically \u2014 any Twilio error code (e.g. 11200 'HTTP retrieval failure' or 32017 'unreachable') that explains why a call dropped. Use this to root-cause client-side 31005 errors.", "operationId": "twilio_recent_calls_api_twilio_recent_calls_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/voice-probe": { "get": { "tags": [ "Business" ], "summary": "Probe our /api/twilio/voice endpoint (bypasses signature check)", "description": "Simulates a Twilio POST to /api/twilio/voice with a fake From/To pair and returns the TwiML response body verbatim. Use this to confirm the endpoint produces valid TwiML \u2014 the #1 root cause of Twilio 31005 errors.", "operationId": "twilio_voice_probe_api_twilio_voice_probe_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } } } } }, "/api/admin/email-health": { "get": { "tags": [ "Business" ], "summary": "Recent transactional email delivery attempts", "description": "Returns the last 30 email delivery attempts with their status (sent / queued / failed). Use to root-cause 'password reset email never arrives' style reports. If everything is `queued` with reason 'RESEND_API_KEY missing', configure Resend in Owner Console \u2192 Providers \u2192 Resend. If entries are `failed` with an error message, that error surfaces Resend's own rejection reason.", "operationId": "admin_email_health_api_admin_email_health_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/verify-caller-id": { "post": { "tags": [ "Business" ], "summary": "Start Twilio outbound caller-ID validation", "description": "Twilio places an automated call to the supplied number; the user enters the returned `validation_code` on their dialpad to complete verification. Required on Trial accounts before that number can place inbound calls to your Twilio number (otherwise Twilio rejects with error 21264).", "operationId": "twilio_start_caller_verification_api_twilio_verify_caller_id_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCallerReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/verified-caller/{sid}": { "delete": { "tags": [ "Business" ], "summary": "Remove a verified caller ID", "operationId": "twilio_delete_verified_caller_api_twilio_verified_caller__sid__delete", "parameters": [ { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/ivr": { "get": { "tags": [ "Business" ], "summary": "List IVR flows (admin only)", "operationId": "list_ivr_api_ivr_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } }, "post": { "tags": [ "Business" ], "summary": "Save an IVR flow", "description": "Persists a new IVR graph (nodes + edges). Replaces previous version on next save with the same name.", "operationId": "save_ivr_api_ivr_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IVRSaveReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team": { "get": { "tags": [ "Users" ], "summary": "List teammates (admin/supervisor only)", "description": "Returns every user in the caller's organization including `calls_today` for each.", "operationId": "list_team_api_team_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } }, "post": { "tags": [ "Users" ], "summary": "Invite a new teammate (admin only)", "description": "Creates a user with a username auto-generated from `name` (no email required). The admin then shares the username + password with the teammate privately. **Enforced server-side**: rejected with **402 Payment Required** if the org has no available seats \u2014 the admin must buy more via `POST /api/billing/seats/purchase` first.", "operationId": "add_member_api_team_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "402": { "description": "Payment required \u2014 seat limit reached or downgrade rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Seat limit reached. Purchase more seats to add another member." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team/{user_id}": { "patch": { "tags": [ "Users" ], "summary": "Edit a teammate's credentials + role (admin only)", "description": "Update the target user's username, password, display name and/or role. All fields optional \u2014 send only what you want to change. If the user is bound to a Communication Seat, the seat card label is kept in sync automatically. Role changes are limited to `agent`, `supervisor`, `quality`; admins/owners cannot be edited from here.", "operationId": "edit_team_member_api_team__user_id__patch", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Req" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Users" ], "summary": "Unassign a teammate from their Communication Seat (admin only)", "description": "Removes the user AND frees their Communication Seat so the admin can assign it to a new staff member later. The seat itself stays in the org \u2014 numbers are permanent, only the person behind them changes. Owners cannot be removed. Admins cannot remove themselves (would lock the org out). Call history and SMS owned by the removed user remain intact (org-scoped).", "operationId": "remove_member_api_team__user_id__delete", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/members": { "get": { "tags": [ "Users" ], "summary": "List teammates (for chat member pickers)", "description": "Returns all teammates in the same org (excluding the caller). Any role can call.", "operationId": "team_chat_members_api_team_chat_members_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts in the caller's organization", "description": "Returns up to 500 contacts sorted alphabetically by name. Agent-role users only see contacts they own; admin/supervisor see all org contacts. Pass `?q=` for a case-insensitive substring match on name/phone/email.", "operationId": "list_contacts_api_contacts_get", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Q" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "description": "Creates a contact owned by the current user. Auto-generates a DiceBear initials avatar. **Side effect**: any orphan inbound SMS in this org whose `from_number` matches the new contact's phone are automatically re-linked to the new contact. An SMS is considered orphan if its `contact_id` is null OR points to a contact that no longer exists (self-healing for stale references after a contact deletion).", "operationId": "add_contact_api_contacts_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/contacts/{cid}": { "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "description": "Permanently removes a contact owned by the caller. Agents can only delete their own contacts.", "operationId": "del_contact_api_contacts__cid__delete", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Full replace of name/phone/email/company/tags/notes. Refreshes the avatar if the name changed.", "operationId": "update_contact_api_contacts__cid__put", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/contacts/{cid}/calls": { "get": { "tags": [ "Contacts" ], "summary": "List recent calls touching this contact", "description": "Returns calls (up to `limit`, default 50) where the contact's phone matches either side. Phone numbers are normalised \u2014 leading `1` and non-digits stripped before comparison.", "operationId": "list_contact_calls_api_contacts__cid__calls_get", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/sms": { "get": { "tags": [ "Messages" ], "summary": "List SMS in the caller's organization", "description": "Newest first. Pass `?contact_id=...` to scope to a known contact, or `?from_number=...` to fetch an orphan conversation (inbound from a number without a *live* matching contact \u2014 handles stale contact links).", "operationId": "list_sms_api_sms_get", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" } }, { "name": "from_number", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Number" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Messages" ], "summary": "Send an SMS to a customer", "description": "Sends an SMS via Twilio's Messages API and persists an outbound record. If Twilio isn't configured (no env vars), the message is logged with `status='mock'` so demo flows still work.", "operationId": "send_sms_api_sms_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/sms-inbound": { "post": { "tags": [ "Messages" ], "summary": "Twilio inbound-SMS webhook", "description": "Public Twilio callback \u2014 persists the inbound message + auto-links the contact by `From` number.", "operationId": "twilio_sms_inbound_api_twilio_sms_inbound_post", "responses": { "200": { "description": "Successful Response" } }, "security": [] } }, "/api/twilio/sms-status": { "post": { "tags": [ "Messages" ], "summary": "Twilio outbound-SMS status callback", "description": "Public Twilio callback fired as an outbound message transitions through queued \u2192 sent \u2192 delivered (or failed / undelivered). Updates the matching sms row so the UI can surface failures instead of silently dropping messages.", "operationId": "twilio_sms_status_api_twilio_sms_status_post", "responses": { "200": { "description": "Successful Response" } }, "security": [] } }, "/api/team-chat/threads": { "get": { "tags": [ "Team Chat" ], "summary": "List all chat threads (DMs + groups)", "description": "Returns one entry per teammate (1:1 DM) and one entry per group the caller belongs to, each with `last_message` and `unread` count. Sorted by last activity descending.", "operationId": "team_chat_threads_api_team_chat_threads_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/team-chat/messages": { "get": { "tags": [ "Team Chat" ], "summary": "Fetch messages for a DM or group thread", "description": "Pass exactly one of `with_user` (teammate id) or `group_id`. Auto-marks inbound messages as read for the caller.", "operationId": "team_chat_messages_api_team_chat_messages_get", "parameters": [ { "name": "with_user", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "With User" } }, { "name": "group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Team Chat" ], "summary": "Send a message to a teammate or group", "description": "Pass exactly one target (`to_user_id` OR `group_id`). Body may be empty if `attachments` or `call_room_id` is set. `@username` mentions in the body are auto-extracted to `mentions[]`.", "operationId": "team_chat_send_api_team_chat_messages_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMsgReq" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/groups": { "get": { "tags": [ "Team Chat" ], "summary": "List groups the caller belongs to", "operationId": "list_team_groups_api_team_chat_groups_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } }, "post": { "tags": [ "Team Chat" ], "summary": "Create a new group thread", "description": "The caller is added automatically. Invalid member ids (outside the org) are silently dropped.", "operationId": "create_team_group_api_team_chat_groups_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamGroupCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/groups/{group_id}": { "patch": { "tags": [ "Team Chat" ], "summary": "Rename a group or update its members", "description": "Only the group creator or an admin can edit. The creator can never be removed.", "operationId": "update_team_group_api_team_chat_groups__group_id__patch", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamGroupUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Team Chat" ], "summary": "Delete a group and all its messages", "description": "Only the group creator or an admin can delete. **Irreversible** \u2014 drops every message in the thread.", "operationId": "delete_team_group_api_team_chat_groups__group_id__delete", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/organizations/me/chat-settings": { "get": { "tags": [ "Team Chat" ], "summary": "Get current org chat-settings", "operationId": "get_org_chat_settings_endpoint_api_organizations_me_chat_settings_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } }, "patch": { "tags": [ "Team Chat" ], "summary": "Update org chat-settings (admin only)", "description": "Configure the delete/edit window (in seconds) and whether delete-for-everyone is enabled at all.", "operationId": "update_org_chat_settings_api_organizations_me_chat_settings_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSettingsReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/messages/{msg_id}": { "patch": { "tags": [ "Team Chat" ], "summary": "Edit a team-chat message (sender only)", "description": "Allowed only within the org's `edit_window_seconds` (default 5 minutes).", "operationId": "edit_message_api_team_chat_messages__msg_id__patch", "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Msg Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MsgEditReq" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Team Chat" ], "summary": "Delete a message (`scope` = me / all / recall)", "description": "**`me`**: hide only for the caller. **`recall`**: unsend if the message is still unread by recipients (any age). **`all`**: delete-for-everyone \u2014 sender only, within the org's `delete_window_seconds`, and only if the org admin has not disabled this feature.", "operationId": "delete_message_api_team_chat_messages__msg_id__delete", "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Msg Id" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "default": "me", "title": "Scope" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/messages/{msg_id}/react": { "post": { "tags": [ "Team Chat" ], "summary": "Toggle a reaction on a message", "description": "Allowed emoji: \ud83d\udc4d \u2764\ufe0f \ud83d\ude02 \ud83d\ude2e \ud83d\ude22 \ud83d\ude4f \ud83d\udc4f \ud83d\udd25. Sending the same emoji a second time removes the reaction.", "operationId": "toggle_reaction_api_team_chat_messages__msg_id__react_post", "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Msg Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/models__schemas__ReactReq" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/messages/{msg_id}/pin": { "post": { "tags": [ "Team Chat" ], "summary": "Pin / unpin a message", "operationId": "toggle_pin_api_team_chat_messages__msg_id__pin_post", "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Msg Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/messages/{msg_id}/star": { "post": { "tags": [ "Team Chat" ], "summary": "Star / unstar a message (per-user)", "operationId": "toggle_star_api_team_chat_messages__msg_id__star_post", "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Msg Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/messages/{msg_id}/info": { "get": { "tags": [ "Team Chat" ], "summary": "Read receipts + delivery metadata for a message", "operationId": "message_info_api_team_chat_messages__msg_id__info_get", "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Msg Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/search": { "get": { "tags": [ "Team Chat" ], "summary": "Full-text search across all threads the caller can see", "description": "Substring match on message body + sender name. Pass `kind=dm|group` and/or `with_user`/`group_id` to scope.", "operationId": "search_messages_api_team_chat_search_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "title": "Q" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" } }, { "name": "with_user", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "With User" } }, { "name": "group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/search-advanced": { "get": { "tags": [ "Team Chat" ], "summary": "Filtered search (date range, sender, attachments, links)", "operationId": "search_advanced_api_team_chat_search_advanced_get", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Q" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" } }, { "name": "from_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From User Id" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date From" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date To" } }, { "name": "has_attachments", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Attachments" } }, { "name": "has_links", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Links" } }, { "name": "has_documents", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Documents" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/upload": { "post": { "tags": [ "Team Chat" ], "summary": "Upload an attachment (\u226425 MB)", "description": "Multipart form upload. Returns a `{path, original_filename, content_type, size, kind}` envelope \u2014 pass this as one of the `attachments[]` when sending a message via `POST /api/team-chat/messages`.", "operationId": "upload_team_chat_attachment_api_team_chat_upload_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_team_chat_attachment_api_team_chat_upload_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } }, "413": { "description": "File exceeds 25 MB" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/files/{path}": { "get": { "tags": [ "Team Chat" ], "summary": "Download an attachment (org-scoped)", "description": "Returns the raw file bytes. The caller must belong to the org that uploaded the file.", "operationId": "download_team_chat_file_api_team_chat_files__path__get", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "title": "Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/block/{user_id}": { "post": { "tags": [ "Team Chat" ], "summary": "Block a teammate (DM only)", "description": "Blocked users can't message you and you can't message them until you unblock.", "operationId": "block_user_api_team_chat_block__user_id__post", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Team Chat" ], "summary": "Unblock a teammate", "operationId": "unblock_user_api_team_chat_block__user_id__delete", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/blocked": { "get": { "tags": [ "Team Chat" ], "summary": "List blocked teammates", "operationId": "list_blocked_api_team_chat_blocked_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/team-chat/messages/{msg_id}/forward": { "post": { "tags": [ "Team Chat" ], "summary": "Forward a message to teammates and/or groups", "description": "Pass at least one of `to_user_ids` or `group_ids`. Optional `comment` is prepended.", "operationId": "forward_message_api_team_chat_messages__msg_id__forward_post", "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Msg Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardReq" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/team-chat/messages/{msg_id}/translate": { "post": { "tags": [ "Team Chat" ], "summary": "Translate a message via Claude Sonnet 4.5", "description": "Auto-detects the source language and returns translated text in the requested `target` language code (e.g. `es`, `fr`, `hi`, `ja`). Preserves @mentions, URLs, and emoji.", "operationId": "translate_message_api_team_chat_messages__msg_id__translate_post", "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Msg Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateReq" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "LLM call failed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/calls": { "get": { "tags": [ "Calls" ], "summary": "List calls in the caller's organization", "description": "Returns up to `limit` calls (default 100), newest first. Filter by `direction` (`inbound`/`outbound`) and/or `status` (`completed`/`missed`/`no-answer`/`busy`/`failed`/`in-progress`). Agents only see their own calls; admin/supervisor see all org calls.", "operationId": "list_calls_api_calls_get", "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Direction" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/calls/start": { "post": { "tags": [ "Calls" ], "summary": "Log an outbound call (creates an in-progress record)", "description": "Records a new call. If `from_number_id` is missing or invalid, the first available org virtual number is used. Returns the persisted call document \u2014 finalise it with `POST /api/calls/{cid}/end` once the call disconnects.", "operationId": "start_call_api_calls_start_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/calls/{cid}/end": { "post": { "tags": [ "Calls" ], "summary": "Finalise a call with duration + outcome", "description": "Sets `duration`, final `status`, `recorded` flag, and free-text `notes`. If `recorded=true`, a `recordings` document is also inserted (synthetic in demo data, with a waveform array).", "operationId": "end_call_api_calls__cid__end_post", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallEnd" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/recordings": { "get": { "tags": [ "Calls" ], "summary": "List call recordings", "description": "Returns the 200 most recent recordings the caller can see, each enriched with its parent `call` document.", "operationId": "list_recordings_api_recordings_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/recordings/{rid}/download": { "get": { "tags": [ "Calls" ], "summary": "Get a download URL or synthetic transcript for a recording", "description": "Admin/supervisor/owner only \u2014 **agents receive 403** (compliance / audit policy). Returns the Twilio media URL for real calls, or a synthetic transcript stub for demo recordings (so the UI can still render a downloadable artifact).", "operationId": "download_recording_api_recordings__rid__download_get", "parameters": [ { "name": "rid", "in": "path", "required": true, "schema": { "type": "string", "title": "Rid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/recordings/{rid}/audio": { "get": { "tags": [ "Calls" ], "summary": "Stream a recording's audio bytes (server-side Twilio auth proxy)", "description": "Streams the recording's audio to the browser via our backend so Twilio's Basic-Auth credentials never leak to the client. Same org-scope + seat-gate rules as `/recordings/{id}/download`.", "operationId": "stream_recording_audio_api_recordings__rid__audio_get", "parameters": [ { "name": "rid", "in": "path", "required": true, "schema": { "type": "string", "title": "Rid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/voice": { "post": { "tags": [ "Calls" ], "summary": "Twilio voice webhook (TwiML)", "description": "Public Twilio callback \u2014 DO NOT call from a client. Twilio POSTs here when a call connects to our TwiML App; we respond with TwiML telling Twilio whether to ring agents (inbound PSTN) or dial out (outbound from browser softphone).", "operationId": "twilio_voice_webhook_api_twilio_voice_post", "responses": { "200": { "description": "Successful Response" } }, "security": [] } }, "/api/twilio/voice-inbound": { "post": { "tags": [ "Calls" ], "summary": "Twilio inbound-call webhook (TwiML)", "description": "Legacy inbound webhook used by older purchased numbers; the modern endpoint is `/api/twilio/voice`.", "operationId": "twilio_voice_inbound_api_twilio_voice_inbound_post", "responses": { "200": { "description": "Successful Response" } }, "security": [] } }, "/api/twilio/status": { "post": { "tags": [ "Calls" ], "summary": "Twilio call-status callback", "description": "Public Twilio callback that updates `status`, `duration`, and `ended_at` on the matching call record.", "operationId": "twilio_status_callback_api_twilio_status_post", "responses": { "200": { "description": "Successful Response" } }, "security": [] } }, "/api/twilio/recording": { "post": { "tags": [ "Calls" ], "summary": "Twilio recording-ready callback", "description": "Public Twilio callback that persists the recording URL + duration once Twilio finishes writing the MP3.", "operationId": "twilio_recording_callback_api_twilio_recording_post", "responses": { "200": { "description": "Successful Response" } }, "security": [] } }, "/api/twilio/transfer": { "post": { "tags": [ "Calls" ], "summary": "Transfer a live call (cold or warm)", "description": "Re-routes an in-progress call. **Cold** transfer: customer leg is dialed directly to the target while preserving the original caller ID. **Warm** transfer: customer is moved into a named conference; both agents can join.", "operationId": "twilio_transfer_api_twilio_transfer_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Contact not found" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/conference/add": { "post": { "tags": [ "Calls" ], "summary": "Add a 3rd participant to a live call", "description": "Converts a 2-leg call into a named conference and dials in an additional phone or `client:username`.", "operationId": "twilio_conference_add_api_twilio_conference_add_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConferenceAddReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Contact not found" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/voicemail": { "post": { "tags": [ "Voicemail" ], "summary": "Twilio voicemail-recording callback", "description": "Public Twilio callback fired when a voicemail recording finishes. Persists a row in the `voicemails` collection. The transcription step is **not** automatic \u2014 clients call `POST /api/voicemail/{id}/transcribe` to spend the Whisper credits on-demand.", "operationId": "twilio_voicemail_callback_api_twilio_voicemail_post", "responses": { "200": { "description": "Successful Response" } }, "security": [] } }, "/api/voicemail": { "get": { "tags": [ "Voicemail" ], "summary": "List voicemails (org-scoped)", "description": "Returns the 200 most recent voicemails the caller can see (admin/supervisor: org-wide; agent: own).", "operationId": "list_voicemails_api_voicemail_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/voicemail/unread-count": { "get": { "tags": [ "Voicemail" ], "summary": "Unread voicemail count", "operationId": "voicemail_unread_count_api_voicemail_unread_count_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/voicemail/business-hours": { "get": { "tags": [ "Voicemail" ], "summary": "Get the org's business-hours config", "operationId": "get_business_hours_api_voicemail_business_hours_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } }, "put": { "tags": [ "Voicemail" ], "summary": "Update the org's business-hours config (admin only)", "description": "When `enabled=true`, every inbound call landing on `/api/twilio/voice` outside the window is sent straight to voicemail (skipping the agent ring stage).", "operationId": "set_business_hours_api_voicemail_business_hours_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessHours" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/voicemail/{vid}": { "get": { "tags": [ "Voicemail" ], "summary": "Get a single voicemail", "operationId": "get_voicemail_api_voicemail__vid__get", "parameters": [ { "name": "vid", "in": "path", "required": true, "schema": { "type": "string", "title": "Vid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Voicemail" ], "summary": "Delete a voicemail", "operationId": "delete_voicemail_api_voicemail__vid__delete", "parameters": [ { "name": "vid", "in": "path", "required": true, "schema": { "type": "string", "title": "Vid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/voicemail/{vid}/transcribe": { "post": { "tags": [ "Voicemail" ], "summary": "Transcribe a voicemail via OpenAI Whisper", "description": "Downloads the MP3 from the Twilio recording URL and runs it through `whisper-1`. Returns the transcript synchronously (typically 2-8s for a \u226460s message). Subsequent calls return the cached transcript.", "operationId": "transcribe_voicemail_api_voicemail__vid__transcribe_post", "parameters": [ { "name": "vid", "in": "path", "required": true, "schema": { "type": "string", "title": "Vid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/voicemail/{vid}/mark-read": { "post": { "tags": [ "Voicemail" ], "summary": "Mark a voicemail as heard", "operationId": "mark_voicemail_read_api_voicemail__vid__mark_read_post", "parameters": [ { "name": "vid", "in": "path", "required": true, "schema": { "type": "string", "title": "Vid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/numbers/entitlement": { "get": { "tags": [ "Numbers" ], "summary": "Included-numbers entitlement for the current org", "description": "1 seat = 1 included business number. Returns `included`, `used`, and `remaining`. Toll-free numbers count as `used` too (Version 1 policy). When `remaining <= 0` the UI should suggest adding seats before purchase.", "operationId": "numbers_entitlement_api_numbers_entitlement_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/numbers/catalog": { "get": { "tags": [ "Numbers" ], "summary": "List supported countries and assignment target types", "description": "Powers the Number Purchase wizard. Provider-agnostic.", "operationId": "numbers_catalog_api_numbers_catalog_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/numbers/search": { "get": { "tags": [ "Numbers" ], "summary": "Search purchasable numbers from the configured provider", "description": "Returns candidate numbers matching the filters. `type` accepts `local`, `toll-free`, `mobile`, or `national`. Vanity/pattern filters (`contains`, `starts_with`, `ends_with`) are passed to the provider when supported; ignored otherwise. Response is provider-agnostic.", "operationId": "search_numbers_api_numbers_search_get", "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2", "default": "US", "title": "Country" }, "description": "ISO 3166-1 alpha-2" }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "local", "toll-free", "mobile", "national" ], "type": "string", "default": "local", "title": "Type" } }, { "name": "region", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State / Province", "title": "Region" }, "description": "State / Province" }, { "name": "city", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Locality / City", "title": "City" }, "description": "Locality / City" }, { "name": "area_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 6 }, { "type": "null" } ], "title": "Area Code" } }, { "name": "contains", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10 }, { "type": "null" } ], "description": "Vanity pattern (digits or letters)", "title": "Contains" }, "description": "Vanity pattern (digits or letters)" }, { "name": "starts_with", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8 }, { "type": "null" } ], "title": "Starts With" } }, { "name": "ends_with", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8 }, { "type": "null" } ], "title": "Ends With" } }, { "name": "voice", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Voice" } }, { "name": "sms", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sms" } }, { "name": "mms", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Mms" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "example": { "detail": "Twilio not configured" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/numbers": { "get": { "tags": [ "Numbers" ], "summary": "List virtual numbers (admin/supervisor)", "operationId": "list_numbers_api_numbers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } }, "post": { "tags": [ "Numbers" ], "summary": "Provision a synthetic demo number", "description": "Creates a fake virtual number for demo purposes. For real Twilio numbers see `POST /api/twilio/numbers/buy`.", "operationId": "buy_number_api_numbers_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/numbers/{num_id}": { "delete": { "tags": [ "Numbers" ], "summary": "Release a virtual number", "operationId": "release_number_api_numbers__num_id__delete", "parameters": [ { "name": "num_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Num Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/twilio/numbers/buy": { "post": { "tags": [ "Numbers" ], "summary": "Purchase a real Twilio number (optionally a specific one from search)", "description": "If `phone_number` is provided, buys that exact number. Otherwise picks the first available number matching `country` + `type` (legacy behavior). If `assign_to` is provided, the number is atomically assigned after purchase.", "operationId": "twilio_buy_real_number_api_twilio_numbers_buy_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Contact not found" } } } }, "503": { "description": "An external dependency (Twilio, storage, LLM) is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Twilio not configured" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/numbers/{num_id}/assign": { "post": { "tags": [ "Numbers" ], "summary": "Assign or reassign a number to a routing destination", "description": "Assignment is org-scoped and audit-logged. `target_type=unassigned` clears the current assignment (the number becomes idle / parked). Active calls on this number are NOT interrupted.", "operationId": "assign_number_api_numbers__num_id__assign_post", "parameters": [ { "name": "num_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Num Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignReq" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/numbers/{num_id}/assignee": { "patch": { "tags": [ "Numbers" ], "summary": "Edit the credentials of the staff member assigned to this number", "description": "Updates the username, password, and/or display name of the currently assigned staff user. The number stays with the same user; only their credentials change. All fields optional \u2014 send only what you want to update.", "operationId": "edit_assignee_api_numbers__num_id__assignee_patch", "parameters": [ { "name": "num_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Num Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssigneeEditReq" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/numbers/{num_id}/reassign-new-user": { "post": { "tags": [ "Numbers" ], "summary": "Reassign this number to a brand-new staff member", "description": "Creates a fresh staff user with the provided credentials and points this number at them. The previous user (if any) loses access to this seat's line \u2014 their account is preserved and can be reassigned later.", "operationId": "reassign_new_user_api_numbers__num_id__reassign_new_user_post", "parameters": [ { "name": "num_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Num Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssigneeNewUserReq" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/numbers/bulk-assign": { "post": { "tags": [ "Numbers" ], "summary": "Bulk assign or reassign multiple numbers", "description": "Applies the same target to all provided number ids atomically per record.", "operationId": "bulk_assign_numbers_api_numbers_bulk_assign_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignReq" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs": { "get": { "tags": [ "Admin" ], "summary": "List every customer organization (platform owner only)", "description": "Returns all orgs with user/call counts and computed monthly charge. KYC media is excluded.", "operationId": "owner_list_orgs_api_owner_orgs_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } }, "post": { "tags": [ "Admin" ], "summary": "Create an organization manually (owner only)", "description": "Bypass-KYC creation path used by the platform owner to onboard customers via direct contracts.", "operationId": "owner_create_org_api_owner_orgs_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerCreateOrg" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Email already registered" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/revenue": { "get": { "tags": [ "Admin" ], "summary": "Platform revenue summary (owner only)", "description": "Computes MRR/ARR across active orgs, broken down by plan tier. Prices are pulled LIVE from Stripe (source of truth) \u2014 never hardcoded. Paying-seat counts use `seats_total` (the quantity we actually bill in Stripe), so managerial-only admins who haven't purchased their own Communication Seat are correctly excluded.", "operationId": "owner_revenue_api_owner_revenue_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/owner/orgs/{org_id}": { "get": { "tags": [ "Admin" ], "summary": "Get a single org with its users (owner only)", "operationId": "owner_get_org_api_owner_orgs__org_id__get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Hard-delete an organization + all its data (owner only)", "description": "Cascade-deletes users, contacts, calls, recordings, SMS, virtual numbers, and IVR flows.", "operationId": "owner_delete_api_owner_orgs__org_id__delete", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Admin" ], "summary": "Update org details (owner only)", "description": "Patches any combination of `name`, `plan`, `status`, `seats_total`, `owner_email`, `kyc_status`, `type`. Each field is optional. Writes an audit-log entry.", "operationId": "owner_update_org_api_owner_orgs__org_id__patch", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerOrgUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/approve": { "post": { "tags": [ "Admin" ], "summary": "Approve a pending/intent org (owner only)", "description": "Owner-approve manually provisions an organisation. Two paths:\n\n1. `status=\"intent\"` \u2014 the org came in through the Signup-Intent funnel\n but hasn't paid yet. Owner-approve treats this as a comped account:\n routes through `finalize_intent()` so the org is activated AND the\n Communication Seats are provisioned (empty `virtual_numbers` rows in\n `lifecycle_state=\"purchased\"`), exactly like a successful Stripe\n payment would have. The admin then walks the WelcomeWizard the\n moment they log in.\n\n2. `status=\"pending\"` \u2014 a legacy signup awaiting review. Just flips the\n status to `active` and stamps `kyc_status=\"approved\"`.\n\nEither way the welcome email fires afterwards.", "operationId": "owner_approve_api_owner_orgs__org_id__approve_post", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/suspend": { "post": { "tags": [ "Admin" ], "summary": "Suspend an active org (owner only)", "operationId": "owner_suspend_api_owner_orgs__org_id__suspend_post", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/reject": { "post": { "tags": [ "Admin" ], "summary": "Reject a pending KYC (owner only)", "operationId": "owner_reject_api_owner_orgs__org_id__reject_post", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/kyc/veriff/status": { "get": { "tags": [ "Admin" ], "summary": "Introspect the Veriff configuration (owner only)", "description": "Reports which Mongo collection Veriff was found in, whether api_key / shared_secret / base_url resolved to non-empty values, and what the effective base URL will be. Never returns the secret values themselves \u2014 just booleans + last-4 of the API key.", "operationId": "owner_veriff_status_api_owner_kyc_veriff_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/owner/kyc/veriff/reset": { "delete": { "tags": [ "Admin" ], "summary": "Delete the Veriff record from every collection (owner only)", "description": "Nukes any existing Veriff entry from provider_configs, custom_providers, and provider_registry \u2014 so the operator can re-register via the Marketplace form without the 'already exists' block. Idempotent.", "operationId": "owner_veriff_reset_api_owner_kyc_veriff_reset_delete", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/owner/feature-flags": { "get": { "tags": [ "Admin" ], "summary": "List every feature flag currently set (owner only)", "operationId": "owner_list_feature_flags_api_owner_feature_flags_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/owner/feature-flags/{name}": { "put": { "tags": [ "Admin" ], "summary": "Set a feature flag (owner only)", "description": "Value takes effect immediately \u2014 no redeploy required.", "operationId": "owner_set_feature_flag_api_owner_feature_flags__name__put", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureFlagUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/stats": { "get": { "tags": [ "Admin" ], "summary": "Platform-wide counts (owner only)", "description": "Total orgs, pending/active/suspended counts, total users, total calls.", "operationId": "owner_stats_api_owner_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/owner/data-integrity": { "get": { "tags": [ "Admin" ], "summary": "Cross-tenant data-integrity scan (owner only)", "description": "Walks every organization in the platform and counts data-integrity signals: SMS records pointing to deleted contacts (`stale_contact_links`), call records pointing to deleted contacts (`stale_call_contact_links`), and meetings whose organizer/participants reference deleted users (`stale_meeting_user_refs`). Returns per-org counts plus a `worst` list sorted by total issues descending. Use the heal endpoint to auto-null those references so they surface as orphans / unknown in the per-tenant UI.", "operationId": "owner_data_integrity_api_owner_data_integrity_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/owner/data-integrity/heal/{org_id}": { "post": { "tags": [ "Admin" ], "summary": "Self-heal stale references in one org (owner only)", "description": "Nulls out stale `contact_id` fields on SMS and call records that point to deleted contacts in the given org. SMS records will then surface as orphans in the tenant's Messages UI; calls will display as 'Unknown' on the call log. Meeting references are NOT auto-healed (deleting an organizer is rare and may indicate the meeting itself should be cancelled). Returns the number of records updated per collection.", "operationId": "owner_heal_org_api_owner_data_integrity_heal__org_id__post", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/activity": { "get": { "tags": [ "Admin" ], "summary": "Platform-wide activity feed (owner only)", "description": "Merged time-sorted activity across every organization: calls, SMS, meetings, new contacts, user signups, owner audit actions. Each row is normalised to {type, org_id, org_name, actor, summary, at}. Filter with `org_id`, `type`, or `q` (substring of summary). Returns newest first.", "operationId": "owner_activity_api_owner_activity_get", "parameters": [ { "name": "org_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Org Id" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "call|sms|meeting|contact|user|audit", "title": "Type" }, "description": "call|sms|meeting|contact|user|audit" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "substring filter on summary", "title": "Q" }, "description": "substring filter on summary" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/search": { "get": { "tags": [ "Admin" ], "summary": "Cross-tenant search (owner only)", "description": "Searches users (name/email), contacts (name/phone), virtual numbers, and orgs by name. Returns up to 50 matches across all tenants.", "operationId": "owner_search_api_owner_search_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "title": "Q" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/deep": { "get": { "tags": [ "Admin" ], "summary": "Org deep snapshot (owner only)", "description": "Comprehensive overview of a single tenant: org metadata, all team members (with last_active timestamps inferred from latest call / sms / meeting), counts of every resource (contacts, calls, recordings, sms, meetings, voicemails, numbers), and quick billing snapshot (MRR + plan).", "operationId": "owner_org_deep_api_owner_orgs__org_id__deep_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/users": { "get": { "tags": [ "Admin" ], "summary": "List all users of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__users_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 500, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/contacts": { "get": { "tags": [ "Admin" ], "summary": "List all contacts of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__contacts_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/calls": { "get": { "tags": [ "Admin" ], "summary": "List all calls of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__calls_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/recordings": { "get": { "tags": [ "Admin" ], "summary": "List all recordings of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__recordings_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/sms": { "get": { "tags": [ "Admin" ], "summary": "List all SMS of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__sms_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/meetings": { "get": { "tags": [ "Admin" ], "summary": "List all meetings of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__meetings_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/voicemails": { "get": { "tags": [ "Admin" ], "summary": "List all voicemails of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__voicemails_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/numbers": { "get": { "tags": [ "Admin" ], "summary": "List all virtual numbers of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__numbers_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/ivr": { "get": { "tags": [ "Admin" ], "summary": "List all IVR flows of an org (owner)", "operationId": "_list_api_owner_orgs__org_id__ivr_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/export": { "get": { "tags": [ "Admin" ], "summary": "Export full org data as JSON (owner only)", "description": "Returns the entire org's persisted state (org doc + every collection scoped to org_id) as a single JSON document. Use for GDPR data-subject requests or backup before deletion.", "operationId": "owner_export_org_api_owner_orgs__org_id__export_get", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/users/{user_id}": { "patch": { "tags": [ "Admin" ], "summary": "Edit any user across the platform (owner only)", "description": "Patch `name`, `email`, `role`, or `deleted` (soft delete flag) on any user in any org. Writes an audit entry.", "operationId": "owner_update_user_api_owner_users__user_id__patch", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerUserUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Soft-delete a user (owner only)", "description": "Marks the user as `deleted: true`. They will no longer be able to log in and won't count against seat quotas, but their history (calls, SMS) is preserved.", "operationId": "owner_delete_user_api_owner_users__user_id__delete", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/users/{user_id}/reset-password": { "post": { "tags": [ "Admin" ], "summary": "Force-reset a user's password (owner only)", "description": "Owner sets a new password for any user. The user is **not** notified by email \u2014 owner must communicate the temp password out-of-band. Logged in the audit trail.", "operationId": "owner_reset_password_api_owner_users__user_id__reset_password_post", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerPasswordReset" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/users/{user_id}/force-logout": { "post": { "tags": [ "Admin" ], "summary": "Force-logout a user everywhere (owner only)", "description": "Revokes every refresh session and invalidates all live access tokens via a session-epoch bump. The user must sign in again on every device.", "operationId": "owner_force_logout_api_owner_users__user_id__force_logout_post", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/users/{user_id}/unlock": { "post": { "tags": [ "Admin" ], "summary": "Unlock a user account (owner only)", "description": "Clears the `is_locked` flag AND wipes all brute-force lockout counters for the user's email so they can sign in immediately.", "operationId": "owner_unlock_user_api_owner_users__user_id__unlock_post", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/users/{user_id}/reset-mfa": { "post": { "tags": [ "Admin" ], "summary": "Reset a user's MFA (owner only)", "description": "Deletes every trusted device and pending email-OTP challenge for the user. On next login they will be re-challenged with a fresh OTP.", "operationId": "owner_reset_mfa_api_owner_users__user_id__reset_mfa_post", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/users/{user_id}/force-password-change": { "post": { "tags": [ "Admin" ], "summary": "Force a user to change their password at next login (owner only)", "description": "Sets `must_change_password`, revokes every session and invalidates live tokens. The user must sign in and immediately set a new password before using the app.", "operationId": "owner_force_password_change_api_owner_users__user_id__force_password_change_post", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/orgs/{org_id}/transfer-ownership": { "post": { "tags": [ "Admin" ], "summary": "Transfer organization ownership to another user (owner only)", "description": "Makes the target user the org's primary admin. Safeguards: the target must belong to the org and be active (not deleted, suspended or locked). Non-admin targets are promoted to admin as part of the transfer. The previous primary admin keeps their admin role.", "operationId": "owner_transfer_ownership_api_owner_orgs__org_id__transfer_ownership_post", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerTransferOwnership" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/users/{user_id}/impersonate": { "post": { "tags": [ "Admin" ], "summary": "Begin impersonating a user (owner only) \u2014 swaps the active session cookies", "description": "Swaps the caller's HttpOnly auth cookies to a new pair authenticating AS the target user. The owner's previous session is preserved on the frontend via a special `owner_resume_token` cookie so the 'Exit impersonation' button can restore them in one click. Every impersonation is audit-logged.", "operationId": "owner_impersonate_api_owner_users__user_id__impersonate_post", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found or not visible to this user.", "content": { "application/json": { "example": { "detail": "Contact not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "400": { "description": "Bad request \u2014 validation or business rule violated.", "content": { "application/json": { "example": { "detail": "Email already registered" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/impersonate/stop": { "post": { "tags": [ "Admin" ], "summary": "Stop impersonating and restore the owner session (owner-or-impersonator only)", "description": "Reads `owner_resume_token` and swaps the cookies back to the owner. Idempotent.", "operationId": "owner_impersonate_stop_api_owner_impersonate_stop_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not authenticated" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Admin only" } } } } } } }, "/api/owner/audit-log": { "get": { "tags": [ "Admin" ], "summary": "Owner audit log (owner only)", "description": "Returns the immutable trail of every privileged owner action (org edits, user edits, password resets, impersonation, deletes, exports, data-integrity heals). Filter by `org_id`, `action`, or `actor_id`.", "operationId": "owner_audit_log_api_owner_audit_log_get", "parameters": [ { "name": "org_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Org Id" } }, { "name": "action", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid auth token.", "content": { "application/json": { "example": { "detail": "Not authenticated" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated but lacks the required role / scope.", "content": { "application/json": { "example": { "detail": "Admin only" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/owner/recordings/{rid}/stream": { "get": { "tags": [ "Admin" ], "summary": "Stream a call recording (owner only)", "description": "Streams the audio of any recording on the platform through the backend. For real Twilio recordings, the backend fetches with HTTP Basic Auth (account SID + auth token) and pipes the response; for synthetic/demo recordings, returns a JSON 404. Use `