{"openapi":"3.1.0","info":{"title":"Ringnity Developer Platform API","version":"0.2.0-draft","summary":"Public REST contract for Ringnity SDKs and customer backend integrations.","description":"Draft OpenAPI contract for the Ringnity Developer Platform.\n\nThis contract powers Scalar docs, generated SDK clients, Bruno tests, and\nbackend conformance checks. Realtime chat, internet call, AI streaming, and\nlive report updates are documented separately in the Ringnity realtime\ncontract.\n","contact":{"name":"Ringnity Support","email":"support@ringnity.com"}},"servers":[{"url":"https://api.ringnity.com/api","description":"Production"},{"url":"http://localhost:8192/api","description":"Local development"}],"x-ringnity-contract-status":"draft","x-ringnity-oauth-scope-coverage":{"description":"OpenAPI coverage map for OAuth scopes that are still marked `planned` in the\ndashboard scope catalog. This map documents the intended public REST\noperation coverage without enabling the scopes at runtime. Scopes with\n`openApiStatus: no-public-operation-yet` intentionally remain visible as\nroadmap scopes only.\n","plannedScopes":{"offline_access":{"openApiStatus":"documented","operationIds":["exchangeRingnityOAuthToken","revokeRingnityOAuthToken"],"notes":"Refresh-token issuance/exchange/revoke is represented by the OAuth token lifecycle endpoints."},"user.profile.read":{"openApiStatus":"documented","operationIds":["getRingnityOAuthUserInfo","getAgentProfile"],"notes":"OIDC userinfo covers identity profile claims; Agent CRM profile covers runtime agent identity."},"user.profile.write":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Profile mutation is still dashboard/internal and should not be exposed as public OAuth API until policy and audit are finalized."},"user.avatar.read":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Avatar metadata is not yet exposed as a standalone public REST contract."},"user.avatar.write":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Avatar upload remains internal until media ownership and audit rules are public."},"tenant.profile.read":{"openApiStatus":"documented","operationIds":["getServerTenant","getAdminTenant","getRingnityOAuthUserInfo"],"notes":"Tenant identity/profile reads are covered through Server API, Admin SDK, and OIDC claims."},"tenant.profile.write":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Tenant profile mutation is not yet a public OAuth-backed contract."},"tenant.branding.read":{"openApiStatus":"documented","operationIds":["bootstrapRuntime","getAdminTenant"],"notes":"Runtime bootstrap and Admin SDK tenant data expose read-only branding/runtime identity."},"tenant.branding.write":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Branding mutation remains internal until media upload and audit policy are public."},"tenant.settings.read":{"openApiStatus":"documented","operationIds":["getDeveloperSettings","getAdminReadiness","getAdminServices"],"notes":"Read-only developer/admin settings are already present in the public contract."},"tenant.settings.write":{"openApiStatus":"partial","operationIds":["updateDeveloperAllowedDomains"],"notes":"Only allowed-domain settings have a public mutation contract today."},"tenant.domains.read":{"openApiStatus":"documented","operationIds":["getAdminDomains","getDeveloperSettings"],"notes":"Domain reads are covered by Admin SDK domains and dashboard developer settings."},"tenant.domains.write":{"openApiStatus":"documented","operationIds":["updateDeveloperAllowedDomains"],"notes":"Allowed-domain replacement is documented as the public write surface."},"staff.read":{"openApiStatus":"documented","operationIds":["getAdminStaffSummary","getAgentProfile"],"notes":"Current public surface is summary/profile read, not full staff directory export."},"staff.write":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Staff mutation remains dashboard/internal pending permission and audit review."},"staff.invite":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Staff invite is not yet exposed as public OAuth API."},"staff.disable":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Staff disable is not yet exposed as public OAuth API."},"runtime.tokens.write":{"openApiStatus":"documented","operationIds":["createRuntimeSession","createVisitorContextToken","createAgentToken","createAdminToken"],"notes":"Runtime token/session issuance is covered by SDK session and Server API token endpoints."},"runtime.sessions.read":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Active runtime-session listing is not yet part of the public REST contract."},"runtime.sessions.write":{"openApiStatus":"documented","operationIds":["createRuntimeSession","registerDevicePushToken","unregisterDevicePushToken"],"notes":"Session creation and device registration lifecycle are documented."},"agents.read":{"openApiStatus":"documented","operationIds":["getAgentProfile","getAdminStaffSummary"],"notes":"Agent profile and staff summary are public read surfaces; full dashboard agent lists remain internal."},"agents.write":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Agent profile/staff mutation is not yet exposed as public OAuth API."},"agents.presence.read":{"openApiStatus":"documented","operationIds":["getAgentPresence"],"notes":"Agent SDK presence read is documented."},"agents.presence.write":{"openApiStatus":"documented","operationIds":["updateAgentPresence"],"notes":"Agent SDK presence update is documented."},"contacts.read":{"openApiStatus":"documented","operationIds":["listContacts","getContact"],"notes":"Server API contact reads are documented."},"contacts.write":{"openApiStatus":"documented","operationIds":["upsertContact","updateContact"],"notes":"Server API contact upsert/update are documented."},"contacts.delete":{"openApiStatus":"documented","operationIds":["deleteContact"],"notes":"Contact deletion is exposed through the tenant-scoped Server API contact endpoint."},"conversations.read":{"openApiStatus":"documented","operationIds":["listAgentConversations","getAgentConversation","listAgentConversationMessages","getVisitorConversation"],"notes":"Agent and visitor conversation read contracts are documented."},"conversations.write":{"openApiStatus":"documented","operationIds":["createVisitorConversation","sendVisitorConversationMessage","editVisitorConversationMessage","sendAgentConversationMessage","markAgentMessageRead"],"notes":"Message send/edit/read workflows are documented."},"conversations.assign":{"openApiStatus":"documented","operationIds":["assignAgentConversation"],"notes":"Agent SDK assignment supports accepting, assigning, or transferring a conversation within tenant visibility rules."},"conversations.close":{"openApiStatus":"documented","operationIds":["closeAgentConversation"],"notes":"Agent conversation close is documented."},"calls.read":{"openApiStatus":"documented","operationIds":["getCallSession","getServerReportSummary","getAdminReportSummary"],"notes":"Call session reads and reporting surfaces are documented."},"calls.write":{"openApiStatus":"documented","operationIds":["createCallSession","endCallSession"],"notes":"Product-level call session create/end are documented."},"calls.recordings.read":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Recording access policy is not yet public."},"calls.recordings.delete":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Recording deletion is not yet public."},"ai.read":{"openApiStatus":"documented","operationIds":["getAiVisitorRouting","getAdminAiReadiness"],"notes":"Visitor AI routing and admin readiness are documented."},"ai.write":{"openApiStatus":"documented","operationIds":["createAiVisitorConversation","sendAiVisitorMessage","createAiVisitorRealtimeCall"],"notes":"Visitor AI conversation/chat/realtime-call write surfaces are documented."},"ai.knowledge.read":{"openApiStatus":"documented","operationIds":["searchAiVisitorKnowledge"],"notes":"Visitor knowledge search is documented; admin knowledge metadata is still internal."},"ai.knowledge.write":{"openApiStatus":"documented","operationIds":["uploadAdminKnowledgeDocument","ingestAdminKnowledgeUrl","reindexAdminKnowledge","deleteAdminKnowledge"],"notes":"Admin SDK knowledge write operations proxy document upload, URL ingest, reindex, and delete to the AI service."},"ai.usage.read":{"openApiStatus":"partial","operationIds":["getAdminAiReadiness","getServerReportSummary","getAdminReportSummary"],"notes":"Usage is currently visible only through readiness/report summaries."},"reports.read":{"openApiStatus":"documented","operationIds":["getServerReportSummary","getServerReportTimeseries","getAdminReportSummary","getAdminReportTimeseries"],"notes":"Server API and Admin SDK reports are documented."},"reports.export":{"openApiStatus":"documented","operationIds":["exportServerReport","exportAdminReport"],"notes":"Server API and Admin SDK report exports are available as JSON or CSV downloads."},"webhooks.read":{"openApiStatus":"documented","operationIds":["listWebhooks","listWebhookDeliveries"],"notes":"Webhook config and delivery reads are documented."},"webhooks.write":{"openApiStatus":"documented","operationIds":["createWebhook","updateWebhook"],"notes":"Webhook create/update are documented."},"webhooks.delete":{"openApiStatus":"documented","operationIds":["disableWebhook"],"notes":"The public contract disables webhook endpoints rather than hard-deleting them."},"webhooks.test":{"openApiStatus":"documented","operationIds":["testWebhook"],"notes":"Webhook test delivery is documented."},"developer.write":{"openApiStatus":"documented","operationIds":["updateDeveloperAllowedDomains","testDeveloperSdkSettings"],"notes":"Public developer settings writes are currently limited to allowed domains and readiness testing."},"sdk.keys.write":{"openApiStatus":"documented","operationIds":["createServerApiCredential","updateServerApiCredential","rotateServerApiCredential","disableServerApiCredential"],"notes":"Server API key lifecycle writes are documented."},"oauth.clients.read":{"openApiStatus":"documented","operationIds":["listOAuthClients"],"notes":"OAuth client registry read is documented."},"oauth.clients.write":{"openApiStatus":"documented","operationIds":["createOAuthClient","updateOAuthClient","rotateOAuthClientSecret","revokeOAuthClient","deleteRevokedOAuthClient"],"notes":"OAuth client lifecycle writes are documented."},"media.read":{"openApiStatus":"partial","operationIds":["listAgentConversationMessages","getVisitorConversation"],"notes":"Media can appear in conversation payloads, but there is no standalone media-read API yet."},"media.write":{"openApiStatus":"documented","operationIds":["createVisitorConversationAttachment","uploadVisitorConversationAttachment"],"notes":"Visitor chat attachment create/upload are documented."},"media.delete":{"openApiStatus":"documented","operationIds":["deleteAgentConversationAttachment"],"notes":"Agent SDK can remove a conversation attachment by soft-deleting the attachment message for auditability."},"billing.read":{"openApiStatus":"documented","operationIds":["getAdminSubscription"],"notes":"Admin subscription read is documented."},"billing.write":{"openApiStatus":"no-public-operation-yet","operationIds":[],"notes":"Billing mutation remains outside the public developer contract."}}},"tags":[{"name":"Runtime Bootstrap","description":"Public website and mobile runtime bootstrap APIs."},{"name":"Developer Settings","description":"Dashboard developer settings and Server API key management."},{"name":"Dashboard Auth","description":"First-party owner and workspace JWT sessions for ringnity.com and tenant dashboards."},{"name":"Login with Ringnity","description":"OAuth2 and OpenID Connect identity login for WordPress, CMS, CRM, mobile apps, and partner portals."},{"name":"Server API","description":"Customer backend APIs using secret Server API keys."},{"name":"Webhooks","description":"Customer backend webhook configuration and delivery history."},{"name":"Agent CRM","description":"Agent/CRM HTTP APIs using short-lived agent tokens."},{"name":"Admin Reports","description":"Admin readiness, tenant status, service status, and reporting APIs."},{"name":"Platform Administration","description":"Platform-owner APIs for Ringnity product configuration."},{"name":"Calls","description":"Product-level internet audio/video call APIs that hide media transport details."},{"name":"Chat","description":"Chat conversation REST APIs."},{"name":"AI","description":"AI chat, routing, and readiness REST APIs."}],"paths":{"/sdk/health":{"get":{"tags":["Runtime Bootstrap"],"operationId":"getRuntimeHealth","summary":"Check public SDK runtime health.","responses":{"200":{"description":"Runtime API is reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}}}}},"/sdk/bootstrap":{"get":{"tags":["Runtime Bootstrap"],"operationId":"bootstrapRuntime","summary":"Resolve tenant branding, services, and runtime capabilities.","parameters":[{"$ref":"#/components/parameters/TenantSlugQuery"},{"$ref":"#/components/parameters/PublicKeyQuery"},{"$ref":"#/components/parameters/DebugQuery"}],"responses":{"200":{"description":"Tenant runtime bootstrap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeBootstrapEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/sdk/session":{"post":{"tags":["Runtime Bootstrap"],"operationId":"createRuntimeSession","summary":"Create a short-lived runtime session token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRuntimeSessionRequest"}}}},"responses":{"201":{"description":"Runtime session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeSessionEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/sdk/devices/push-token":{"post":{"tags":["Runtime Bootstrap"],"operationId":"registerDevicePushToken","summary":"Register or refresh a mobile push token for SDK runtime notifications.","security":[{"RuntimeBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterDevicePushTokenRequest"}}}},"responses":{"201":{"description":"Device push token registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicePushTokenEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}},"delete":{"tags":["Runtime Bootstrap"],"operationId":"unregisterDevicePushToken","summary":"Disable a previously registered SDK device push token.","security":[{"RuntimeBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnregisterDevicePushTokenRequest"}}}},"responses":{"200":{"description":"Device push token disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicePushTokenDisabledEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/owner-login":{"post":{"tags":["Dashboard Auth"],"operationId":"loginOwner","summary":"Sign in a tenant owner on ringnity.com.","description":"Returns an owner-scoped JWT pair. The response keeps `sessionToken` as a deprecated alias of `accessToken`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerLoginRequest"}}}},"responses":{"200":{"description":"Owner session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerSessionEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/owner-google-login":{"post":{"tags":["Dashboard Auth"],"operationId":"loginOwnerWithGoogle","summary":"Sign in a tenant owner with Google Identity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerGoogleLoginRequest"}}}},"responses":{"200":{"description":"Owner session or registration handoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerGoogleLoginEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/owner-me":{"get":{"tags":["Dashboard Auth"],"operationId":"getOwnerSession","summary":"Read the current owner session profile.","security":[{"OwnerBearer":[]}],"responses":{"200":{"description":"Owner session profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerMeEnvelope"}}}},"401":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/owner-refresh":{"post":{"tags":["Dashboard Auth"],"operationId":"refreshOwnerSession","summary":"Rotate an owner refresh token and return a new owner access token.","description":"Uses the `ownerRefreshToken` httpOnly cookie by default. A body refresh token may be supplied by trusted clients.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}}},"responses":{"200":{"description":"Refreshed owner token pair.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerRefreshEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/owner-logout":{"post":{"tags":["Dashboard Auth"],"operationId":"logoutOwner","summary":"Revoke the owner refresh token and clear owner auth cookies.","responses":{"200":{"description":"Owner logged out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}}}}},"/auth/workspace-entry-token":{"post":{"tags":["Dashboard Auth"],"operationId":"createWorkspaceEntryToken","summary":"Create a one-time workspace auto-login token from an owner token.","description":"Bridges ringnity.com owner auth into a separate workspace session on `{slug}.ringnity.com`.","security":[{"OwnerBearer":[]}],"responses":{"200":{"description":"One-time workspace entry token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceEntryTokenEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/workspace-login":{"post":{"tags":["Dashboard Auth"],"operationId":"loginWorkspace","summary":"Sign in a workspace user on `{slug}.ringnity.com`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceLoginRequest"}}}},"responses":{"200":{"description":"Workspace session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceSessionEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/workspace-auto-login":{"get":{"tags":["Dashboard Auth"],"operationId":"autoLoginWorkspace","summary":"Exchange a one-time workspace entry token for a workspace session.","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workspace session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceAutoLoginEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/workspace-refresh":{"post":{"tags":["Dashboard Auth"],"operationId":"refreshWorkspaceSession","summary":"Rotate a workspace refresh token and return a new workspace access token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}}},"responses":{"200":{"description":"Refreshed workspace token pair.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceRefreshEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/auth/workspace-logout":{"post":{"tags":["Dashboard Auth"],"operationId":"logoutWorkspace","summary":"Revoke a workspace refresh token.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}}},"responses":{"200":{"description":"Workspace user logged out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}}}}},"/sdk/developer":{"get":{"tags":["Developer Settings"],"operationId":"getDeveloperSettings","summary":"Read dashboard Developer SDK settings for the logged-in tenant.","security":[{"DashboardBearer":[]}],"responses":{"200":{"description":"Developer settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperSettingsEnvelope"}}}},"401":{"$ref":"#/components/responses/ErrorResponse"}}}},"/sdk/developer/allowed-domains":{"put":{"tags":["Developer Settings"],"operationId":"updateDeveloperAllowedDomains","summary":"Replace allowed browser/mobile origins for public SDK runtime.","security":[{"DashboardBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAllowedDomainsRequest"}}}},"responses":{"200":{"description":"Allowed domains updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperSettingsEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/sdk/developer/test":{"post":{"tags":["Developer Settings"],"operationId":"testDeveloperSdkSettings","summary":"Run dashboard SDK readiness checks for a supplied origin.","security":[{"DashboardBearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperTestRequest"}}}},"responses":{"200":{"description":"Developer SDK test result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessEnvelope"}}}}}}},"/sdk/developer/server-api-credentials":{"get":{"tags":["Developer Settings"],"operationId":"listServerApiCredentials","summary":"List Server API credentials for the logged-in tenant.","security":[{"DashboardBearer":[]}],"responses":{"200":{"description":"Server API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerApiCredentialListEnvelope"}}}}}},"post":{"tags":["Developer Settings"],"operationId":"createServerApiCredential","summary":"Create a Server API credential and return its secret once.","security":[{"DashboardBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServerApiCredentialRequest"}}}},"responses":{"201":{"description":"Server API credential created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerApiCredentialSecretEnvelope"}}}}}}},"/sdk/developer/server-api-credentials/{credentialId}":{"parameters":[{"$ref":"#/components/parameters/CredentialIdPath"}],"patch":{"tags":["Developer Settings"],"operationId":"updateServerApiCredential","summary":"Update a Server API credential name, scopes, environment, or active state.","security":[{"DashboardBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServerApiCredentialRequest"}}}},"responses":{"200":{"description":"Server API credential updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerApiCredentialEnvelope"}}}}}},"delete":{"tags":["Developer Settings"],"operationId":"disableServerApiCredential","summary":"Disable a Server API credential.","security":[{"DashboardBearer":[]}],"responses":{"200":{"description":"Server API credential disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerApiCredentialEnvelope"}}}}}}},"/sdk/developer/server-api-credentials/{credentialId}/rotate":{"parameters":[{"$ref":"#/components/parameters/CredentialIdPath"}],"post":{"tags":["Developer Settings"],"operationId":"rotateServerApiCredential","summary":"Rotate a Server API credential secret and return the new secret once.","security":[{"DashboardBearer":[]}],"responses":{"200":{"description":"Server API credential rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerApiCredentialSecretEnvelope"}}}}}}},"/sdk/developer/oauth-clients":{"get":{"tags":["Developer Settings"],"operationId":"listOAuthClients","summary":"List Login with Ringnity OAuth clients for the logged-in tenant.","security":[{"DashboardBearer":[]}],"responses":{"200":{"description":"OAuth clients.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientListEnvelope"}}}}}},"post":{"tags":["Developer Settings"],"operationId":"createOAuthClient","summary":"Create a Login with Ringnity OAuth client and return its secret once when confidential.","security":[{"DashboardBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOAuthClientRequest"}}}},"responses":{"201":{"description":"OAuth client created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientSecretEnvelope"}}}}}}},"/sdk/developer/oauth-clients/{oauthClientId}":{"parameters":[{"$ref":"#/components/parameters/OAuthClientIdPath"}],"patch":{"tags":["Developer Settings"],"operationId":"updateOAuthClient","summary":"Update a Login with Ringnity OAuth client.","security":[{"DashboardBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOAuthClientRequest"}}}},"responses":{"200":{"description":"OAuth client updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientEnvelope"}}}}}},"delete":{"tags":["Developer Settings"],"operationId":"revokeOAuthClient","summary":"Revoke a Login with Ringnity OAuth client and its refresh tokens.","security":[{"DashboardBearer":[]}],"responses":{"200":{"description":"OAuth client revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientEnvelope"}}}}}}},"/sdk/developer/oauth-clients/{oauthClientId}/rotate-secret":{"parameters":[{"$ref":"#/components/parameters/OAuthClientIdPath"}],"post":{"tags":["Developer Settings"],"operationId":"rotateOAuthClientSecret","summary":"Rotate a confidential OAuth client secret and return the new secret once.","security":[{"DashboardBearer":[]}],"responses":{"200":{"description":"OAuth client secret rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientSecretEnvelope"}}}}}}},"/sdk/developer/oauth-clients/{oauthClientId}/revoked":{"parameters":[{"$ref":"#/components/parameters/OAuthClientIdPath"}],"delete":{"tags":["Developer Settings"],"operationId":"deleteRevokedOAuthClient","summary":"Permanently delete a revoked Login with Ringnity OAuth client.","description":"This operation only succeeds after the OAuth client has already been revoked.\nActive OAuth clients must be revoked first so refresh tokens are invalidated before the registry record is removed.\n","security":[{"DashboardBearer":[]}],"responses":{"200":{"description":"Revoked OAuth client deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientDeletedEnvelope"}}}},"409":{"$ref":"#/components/responses/ErrorResponse"}}}},"/platform/auth/login":{"post":{"tags":["Platform Administration"],"operationId":"loginPlatformAdmin","summary":"Sign in to the Ringnity platform console.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformLoginRequest"}}}},"responses":{"200":{"description":"Platform admin session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformSessionEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/platform/auth/refresh":{"post":{"tags":["Platform Administration"],"operationId":"refreshPlatformAdminSession","summary":"Rotate a platform console refresh token and return a new session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformRefreshRequest"}}}},"responses":{"200":{"description":"Refreshed platform admin session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformSessionEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/platform/plan-contracts":{"get":{"tags":["Platform Administration"],"operationId":"getPlatformPlanContracts","summary":"Read the canonical plan feature and quota contract matrix.","description":"Returns the feature-key catalog, quota-key catalog, and per-plan\ncontract matrix used by the Ringnity rule engine. This replaces legacy\n`plans.features` and `plans.max_*` fields.\n","security":[{"PlatformBearer":[]}],"responses":{"200":{"description":"Plan contracts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanContractCatalogEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}},"put":{"tags":["Platform Administration"],"operationId":"updatePlatformPlanContracts","summary":"Update the canonical plan feature and quota contract matrix.","security":[{"PlatformBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanContractCatalog"}}}},"responses":{"200":{"description":"Plan contracts updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanContractCatalogEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/platform/ai-balance":{"get":{"tags":["Platform Administration"],"operationId":"getPlatformAiBalance","summary":"Read AI balance, usage, and overage projections for all tenants.","description":"Returns platform-level AI balance visibility for tenant OpenAI-backed usage.\nThe response combines tenant balance, current plan quotas, current-month AI\nusage logs, estimated OpenAI cost, retail charge, and alert levels.\n","security":[{"PlatformBearer":[]}],"responses":{"200":{"description":"AI balance overview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiBalanceOverviewEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/platform/ai-balance/{clientId}/top-up":{"parameters":[{"$ref":"#/components/parameters/ClientIdPath"}],"post":{"tags":["Platform Administration"],"operationId":"topUpPlatformAiBalance","summary":"Add AI prepaid balance for a tenant.","security":[{"PlatformBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiBalanceTopUpRequest"}}}},"responses":{"200":{"description":"Tenant AI balance topped up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiBalanceTopUpEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/platform/ai-balance/{clientId}/settings":{"parameters":[{"$ref":"#/components/parameters/ClientIdPath"}],"put":{"tags":["Platform Administration"],"operationId":"updatePlatformAiBalanceTenantSettings","summary":"Update tenant AI overage and auto top-up controls.","security":[{"PlatformBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiBalanceTenantSettingsRequest"}}}},"responses":{"200":{"description":"Tenant AI balance settings updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiBalanceTenantSettingsEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/platform/ai-pricing":{"get":{"tags":["Platform Administration"],"operationId":"getPlatformAiPricing","summary":"Read AI provider cost, retail markup, and guardrail settings.","description":"Returns the editable AI billing settings used to estimate OpenAI-backed\nchat and voice cost, retail charge, and gross margin.\n","security":[{"PlatformBearer":[]}],"responses":{"200":{"description":"AI pricing settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiPricingCatalogEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}},"put":{"tags":["Platform Administration"],"operationId":"updatePlatformAiPricing","summary":"Update AI provider cost, retail markup, and guardrail settings.","security":[{"PlatformBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiPricingSettingsUpdate"}}}},"responses":{"200":{"description":"AI pricing settings updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiPricingCatalogEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/server/health":{"get":{"tags":["Server API"],"operationId":"getServerApiHealth","summary":"Check Server API credential health.","security":[{"ServerApiKey":[]}],"responses":{"200":{"description":"Server API credential is valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/ErrorResponse"}}}},"/server/tenant":{"get":{"tags":["Server API"],"operationId":"getServerTenant","summary":"Read tenant identity for the current Server API key.","security":[{"ServerApiKey":[]}],"responses":{"200":{"description":"Tenant identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantEnvelope"}}}}}}},"/server/tenant/sdk-readiness":{"get":{"tags":["Server API"],"operationId":"getSdkReadiness","summary":"Read service readiness for SDK launch checks.","security":[{"ServerApiKey":[]}],"responses":{"200":{"description":"SDK readiness.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessEnvelope"}}}}}}},"/server/reports/summary":{"get":{"tags":["Server API"],"operationId":"getServerReportSummary","summary":"Read call, chat, satisfaction, and agent productivity summary.","security":[{"ServerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ReportPeriodQuery"},{"$ref":"#/components/parameters/ReportStartDateQuery"},{"$ref":"#/components/parameters/ReportEndDateQuery"},{"$ref":"#/components/parameters/ReportAgentIdQuery"}],"responses":{"200":{"description":"Report summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportSummaryEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/server/reports/timeseries":{"get":{"tags":["Server API"],"operationId":"getServerReportTimeseries","summary":"Read call, chat, and message trend data.","security":[{"ServerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ReportPeriodQuery"},{"$ref":"#/components/parameters/ReportStartDateQuery"},{"$ref":"#/components/parameters/ReportEndDateQuery"},{"$ref":"#/components/parameters/ReportAgentIdQuery"}],"responses":{"200":{"description":"Report timeseries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportTimeseriesEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/server/reports/export":{"get":{"tags":["Server API"],"operationId":"exportServerReport","summary":"Export call, chat, and agent productivity reports.","description":"Returns a downloadable JSON envelope by default, or CSV when `format=csv`.","security":[{"ServerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ReportPeriodQuery"},{"$ref":"#/components/parameters/ReportStartDateQuery"},{"$ref":"#/components/parameters/ReportEndDateQuery"},{"$ref":"#/components/parameters/ReportAgentIdQuery"},{"$ref":"#/components/parameters/ReportFormatQuery"}],"responses":{"200":{"description":"Report export.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportExportEnvelope"}},"text/csv":{"schema":{"type":"string"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/server/visitor-context-token":{"post":{"tags":["Server API"],"operationId":"createVisitorContextToken","summary":"Create a signed visitor context token for public runtime SDKs.","security":[{"ServerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVisitorContextTokenRequest"}}}},"responses":{"201":{"description":"Visitor context token created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkTokenEnvelope"}}}}}}},"/server/sdk-token/agent":{"post":{"tags":["Server API"],"operationId":"createAgentToken","summary":"Create a short-lived token for CRM/agent SDK runtime.","security":[{"ServerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTokenRequest"}}}},"responses":{"201":{"description":"Agent token created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkTokenEnvelope"}}}}}}},"/server/sdk-token/admin":{"post":{"tags":["Server API"],"operationId":"createAdminToken","summary":"Create a short-lived token for admin/reporting SDK runtime.","security":[{"ServerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdminTokenRequest"}}}},"responses":{"201":{"description":"Admin token created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkTokenEnvelope"}}}}}}},"/server/contacts":{"get":{"tags":["Server API"],"operationId":"listContacts","summary":"List synced customer contacts.","security":[{"ServerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Comma-separated tag filter.","schema":{"type":"string"}}],"responses":{"200":{"description":"Contact list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListEnvelope"}}}}}},"post":{"tags":["Server API"],"operationId":"upsertContact","summary":"Create or update a customer contact.","security":[{"ServerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}},"responses":{"200":{"description":"Contact upserted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactEnvelope"}}}}}}},"/server/contacts/{id}":{"parameters":[{"$ref":"#/components/parameters/ContactIdPath"}],"get":{"tags":["Server API"],"operationId":"getContact","summary":"Read one customer contact.","security":[{"ServerApiKey":[]}],"responses":{"200":{"description":"Contact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactEnvelope"}}}}}},"patch":{"tags":["Server API"],"operationId":"updateContact","summary":"Update one customer contact.","security":[{"ServerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPatchInput"}}}},"responses":{"200":{"description":"Contact updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactEnvelope"}}}}}},"delete":{"tags":["Server API"],"operationId":"deleteContact","summary":"Delete one customer contact.","security":[{"ServerApiKey":[]}],"responses":{"200":{"description":"Contact deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactDeletedEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/server/webhooks":{"get":{"tags":["Webhooks"],"operationId":"listWebhooks","summary":"List webhook endpoints.","security":[{"ServerApiKey":[]}],"responses":{"200":{"description":"Webhook list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListEnvelope"}}}}}},"post":{"tags":["Webhooks"],"operationId":"createWebhook","summary":"Create a webhook endpoint.","security":[{"ServerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}}},"responses":{"201":{"description":"Webhook created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}}}}},"/server/webhooks/deliveries":{"get":{"tags":["Webhooks"],"operationId":"listWebhookDeliveries","summary":"List webhook delivery attempts.","security":[{"ServerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"description":"Webhook deliveries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryListEnvelope"}}}}}}},"/server/webhooks/test":{"post":{"tags":["Webhooks"],"operationId":"testWebhook","summary":"Send a webhook test event.","security":[{"ServerApiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestRequest"}}}},"responses":{"200":{"description":"Webhook test queued or delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestEnvelope"}}}}}}},"/server/webhooks/{id}":{"parameters":[{"$ref":"#/components/parameters/WebhookIdPath"}],"patch":{"tags":["Webhooks"],"operationId":"updateWebhook","summary":"Update a webhook endpoint.","security":[{"ServerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPatchRequest"}}}},"responses":{"200":{"description":"Webhook updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}}}},"delete":{"tags":["Webhooks"],"operationId":"disableWebhook","summary":"Disable a webhook endpoint.","security":[{"ServerApiKey":[]}],"responses":{"200":{"description":"Webhook disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}}}}},"/agent-sdk/me":{"get":{"tags":["Agent CRM"],"operationId":"getAgentProfile","summary":"Read the current agent profile.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Agent profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProfileEnvelope"}}}}}}},"/agent-sdk/presence":{"get":{"tags":["Agent CRM"],"operationId":"getAgentPresence","summary":"Read the current agent presence.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Agent presence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresenceEnvelope"}}}}}},"patch":{"tags":["Agent CRM"],"operationId":"updateAgentPresence","summary":"Update the current agent presence.","security":[{"RuntimeBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePresenceRequest"}}}},"responses":{"200":{"description":"Agent presence updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresenceEnvelope"}}}}}}},"/agent-sdk/conversations":{"get":{"tags":["Agent CRM"],"operationId":"listAgentConversations","summary":"List conversations visible to the current agent.","security":[{"RuntimeBearer":[]}],"parameters":[{"$ref":"#/components/parameters/LimitQuery"},{"$ref":"#/components/parameters/CursorQuery"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"departmentId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Conversation list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationListEnvelope"}}}}}}},"/agent-sdk/conversations/{id}":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"get":{"tags":["Agent CRM"],"operationId":"getAgentConversation","summary":"Read one agent-visible conversation.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationEnvelope"}}}}}}},"/agent-sdk/conversations/{id}/messages":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"get":{"tags":["Agent CRM"],"operationId":"listAgentConversationMessages","summary":"List messages in a conversation.","security":[{"RuntimeBearer":[]}],"parameters":[{"$ref":"#/components/parameters/LimitQuery"},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Message list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageListEnvelope"}}}}}},"post":{"tags":["Agent CRM"],"operationId":"sendAgentConversationMessage","summary":"Send an agent message.","security":[{"RuntimeBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"201":{"description":"Message sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageEnvelope"}}}}}}},"/agent-sdk/conversations/{id}/messages/{messageId}/read":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"},{"$ref":"#/components/parameters/MessageIdPath"}],"post":{"tags":["Agent CRM"],"operationId":"markAgentMessageRead","summary":"Mark an agent conversation message as read.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Message marked read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}}}}},"/agent-sdk/conversations/{id}/messages/{messageId}/attachment":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"},{"$ref":"#/components/parameters/MessageIdPath"}],"delete":{"tags":["Agent CRM"],"operationId":"deleteAgentConversationAttachment","summary":"Delete an attachment-bearing conversation message.","description":"Soft-deletes the chat message that owns the attachment so the action remains auditable.","security":[{"RuntimeBearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteMediaRequest"}}}},"responses":{"200":{"description":"Attachment message deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentDeleteEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/agent-sdk/conversations/{id}/assign":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"post":{"tags":["Agent CRM"],"operationId":"assignAgentConversation","summary":"Assign or transfer a conversation from the agent SDK.","security":[{"RuntimeBearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignConversationRequest"}}}},"responses":{"200":{"description":"Conversation assigned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/agent-sdk/conversations/{id}/close":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"post":{"tags":["Agent CRM"],"operationId":"closeAgentConversation","summary":"Close a conversation from the agent SDK.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Conversation closed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationEnvelope"}}}}}}},"/admin-sdk/tenant":{"get":{"tags":["Admin Reports"],"operationId":"getAdminTenant","summary":"Read tenant and admin identity for admin/reporting SDKs.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Admin tenant identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminTenantEnvelope"}}}}}}},"/admin-sdk/readiness":{"get":{"tags":["Admin Reports"],"operationId":"getAdminReadiness","summary":"Read tenant readiness for admin/reporting SDKs.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Admin readiness.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessEnvelope"}}}}}}},"/admin-sdk/domains":{"get":{"tags":["Admin Reports"],"operationId":"getAdminDomains","summary":"Read allowed SDK domains.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Allowed domains.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainListEnvelope"}}}}}}},"/admin-sdk/services":{"get":{"tags":["Admin Reports"],"operationId":"getAdminServices","summary":"Read service capabilities and admin enablement.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Service capabilities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceListEnvelope"}}}}}}},"/admin-sdk/subscription":{"get":{"tags":["Admin Reports"],"operationId":"getAdminSubscription","summary":"Read subscription and plan data.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionEnvelope"}}}}}}},"/admin-sdk/ai-readiness":{"get":{"tags":["Admin Reports"],"operationId":"getAdminAiReadiness","summary":"Read AI readiness for the tenant.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"AI readiness.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiReadinessEnvelope"}}}}}}},"/admin-sdk/staff-summary":{"get":{"tags":["Admin Reports"],"operationId":"getAdminStaffSummary","summary":"Read staff and department summary data.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Staff summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffSummaryEnvelope"}}}}}}},"/admin-sdk/reports/summary":{"get":{"tags":["Admin Reports"],"operationId":"getAdminReportSummary","summary":"Read call, chat, satisfaction, and agent productivity summary.","security":[{"RuntimeBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ReportPeriodQuery"},{"$ref":"#/components/parameters/ReportStartDateQuery"},{"$ref":"#/components/parameters/ReportEndDateQuery"},{"$ref":"#/components/parameters/ReportAgentIdQuery"}],"responses":{"200":{"description":"Report summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportSummaryEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/admin-sdk/reports/timeseries":{"get":{"tags":["Admin Reports"],"operationId":"getAdminReportTimeseries","summary":"Read call, chat, and message trend data for admin dashboards.","security":[{"RuntimeBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ReportPeriodQuery"},{"$ref":"#/components/parameters/ReportStartDateQuery"},{"$ref":"#/components/parameters/ReportEndDateQuery"},{"$ref":"#/components/parameters/ReportAgentIdQuery"}],"responses":{"200":{"description":"Report timeseries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportTimeseriesEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/admin-sdk/reports/export":{"get":{"tags":["Admin Reports"],"operationId":"exportAdminReport","summary":"Export admin report data.","description":"Returns a downloadable JSON envelope by default, or CSV when `format=csv`.","security":[{"RuntimeBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ReportPeriodQuery"},{"$ref":"#/components/parameters/ReportStartDateQuery"},{"$ref":"#/components/parameters/ReportEndDateQuery"},{"$ref":"#/components/parameters/ReportAgentIdQuery"},{"$ref":"#/components/parameters/ReportFormatQuery"}],"responses":{"200":{"description":"Admin report export.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportExportEnvelope"}},"text/csv":{"schema":{"type":"string"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/admin-sdk/ai/knowledge/documents":{"post":{"tags":["AI"],"operationId":"uploadAdminKnowledgeDocument","summary":"Upload an AI knowledge document for the tenant.","security":[{"RuntimeBearer":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Knowledge document queued or ingested.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiKnowledgeEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/admin-sdk/ai/knowledge/urls":{"post":{"tags":["AI"],"operationId":"ingestAdminKnowledgeUrl","summary":"Ingest an AI knowledge URL for the tenant.","security":[{"RuntimeBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeUrlRequest"}}}},"responses":{"201":{"description":"Knowledge URL queued or ingested.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiKnowledgeEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/admin-sdk/ai/knowledge/{knowledgeItemId}/reindex":{"parameters":[{"$ref":"#/components/parameters/KnowledgeItemIdPath"}],"post":{"tags":["AI"],"operationId":"reindexAdminKnowledge","summary":"Reindex an AI knowledge item.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Knowledge item reindexed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiKnowledgeEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/admin-sdk/ai/knowledge/{knowledgeItemId}":{"parameters":[{"$ref":"#/components/parameters/KnowledgeItemIdPath"}],"delete":{"tags":["AI"],"operationId":"deleteAdminKnowledge","summary":"Delete an AI knowledge item.","security":[{"RuntimeBearer":[]}],"responses":{"200":{"description":"Knowledge item deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiKnowledgeEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/calls/sessions":{"post":{"tags":["Calls"],"operationId":"createCallSession","summary":"Create a product-level internet audio or video call session.","description":"Creates a call session attached to a conversation without exposing low-level media transport details.","security":[{"RuntimeBearer":[]},{"DashboardBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCallSessionRequest"}}}},"responses":{"201":{"description":"Call session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSessionEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/calls/sessions/{callSessionId}":{"parameters":[{"$ref":"#/components/parameters/CallSessionIdPath"}],"get":{"tags":["Calls"],"operationId":"getCallSession","summary":"Read a product-level call session.","security":[{"RuntimeBearer":[]},{"DashboardBearer":[]}],"responses":{"200":{"description":"Call session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSessionEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/calls/sessions/{callSessionId}/end":{"parameters":[{"$ref":"#/components/parameters/CallSessionIdPath"}],"patch":{"tags":["Calls"],"operationId":"endCallSession","summary":"End a product-level call session.","security":[{"RuntimeBearer":[]},{"DashboardBearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndCallSessionRequest"}}}},"responses":{"200":{"description":"Call session ended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSessionEnvelope"}}}},"4XX":{"$ref":"#/components/responses/ErrorResponse"}}}},"/chat/visitor/sessions":{"post":{"tags":["Chat"],"operationId":"createVisitorChatSession","summary":"Create or resolve a visitor chat session.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitorSessionRequest"}}}},"responses":{"201":{"description":"Visitor session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitorSessionEnvelope"}}}}}}},"/chat/visitor/conversations":{"post":{"tags":["Chat"],"operationId":"createVisitorConversation","summary":"Start a visitor chat conversation.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitorConversationRequest"}}}},"responses":{"201":{"description":"Conversation created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationEnvelope"}}}}}}},"/chat/visitor/tickets/open":{"get":{"tags":["Chat"],"operationId":"getVisitorOpenTicket","summary":"Get the visitor open ticket when one exists.","security":[{"RuntimeBearer":[]},{}],"responses":{"200":{"description":"Open ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketEnvelope"}}}}}}},"/chat/visitor/availability":{"get":{"tags":["Chat"],"operationId":"getVisitorChatAvailability","summary":"Read chat availability for the current visitor context.","security":[{"RuntimeBearer":[]},{}],"responses":{"200":{"description":"Chat availability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityEnvelope"}}}}}}},"/chat/visitor/conversations/{conversationId}":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"get":{"tags":["Chat"],"operationId":"getVisitorConversation","summary":"Read a visitor conversation.","security":[{"RuntimeBearer":[]},{}],"responses":{"200":{"description":"Conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationEnvelope"}}}}}}},"/chat/visitor/conversations/{conversationId}/messages":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"post":{"tags":["Chat"],"operationId":"sendVisitorConversationMessage","summary":"Send a visitor chat message.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitorMessageRequest"}}}},"responses":{"201":{"description":"Message sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageEnvelope"}}}}}}},"/chat/visitor/conversations/{conversationId}/messages/{messageId}":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"},{"$ref":"#/components/parameters/MessageIdPath"}],"patch":{"tags":["Chat"],"operationId":"editVisitorConversationMessage","summary":"Edit a visitor chat message.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagePatchRequest"}}}},"responses":{"200":{"description":"Message edited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageEnvelope"}}}}}},"delete":{"tags":["Chat"],"operationId":"deleteVisitorConversationMessage","summary":"Delete a visitor chat message.","security":[{"RuntimeBearer":[]},{}],"responses":{"200":{"description":"Message deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}}}}},"/chat/visitor/conversations/{conversationId}/attachments":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"post":{"tags":["Chat"],"operationId":"createVisitorConversationAttachment","summary":"Create attachment metadata for a visitor conversation.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentRequest"}}}},"responses":{"201":{"description":"Attachment metadata created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentEnvelope"}}}}}}},"/chat/visitor/conversations/{conversationId}/attachments/upload":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"post":{"tags":["Chat"],"operationId":"uploadVisitorConversationAttachment","summary":"Upload a visitor conversation attachment.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Attachment uploaded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentEnvelope"}}}}}}},"/chat/visitor/conversations/{conversationId}/call-links":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"}],"post":{"tags":["Chat"],"operationId":"createVisitorConversationCallLink","summary":"Create an internet call link for a visitor conversation.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallLinkRequest"}}}},"responses":{"201":{"description":"Call link created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallLinkEnvelope"}}}}}}},"/chat/conversations/{conversationId}/messages/{messageId}/delivered":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"},{"$ref":"#/components/parameters/MessageIdPath"}],"post":{"tags":["Chat"],"operationId":"markChatMessageDelivered","summary":"Mark a chat message as delivered.","security":[{"RuntimeBearer":[]},{}],"responses":{"200":{"description":"Delivery receipt recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptEnvelope"}}}}}}},"/chat/conversations/{conversationId}/messages/{messageId}/read":{"parameters":[{"$ref":"#/components/parameters/ConversationIdPath"},{"$ref":"#/components/parameters/MessageIdPath"}],"post":{"tags":["Chat"],"operationId":"markChatMessageRead","summary":"Mark a chat message as read.","security":[{"RuntimeBearer":[]},{}],"responses":{"200":{"description":"Read receipt recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptEnvelope"}}}}}}},"/ai/visitor/routing":{"get":{"tags":["AI"],"operationId":"getAiVisitorRouting","summary":"Read AI routing mode for the visitor context.","security":[{"RuntimeBearer":[]},{}],"responses":{"200":{"description":"AI routing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRoutingEnvelope"}}}}}}},"/ai/visitor/conversations":{"post":{"tags":["AI"],"operationId":"createAiVisitorConversation","summary":"Start an AI visitor conversation.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiConversationRequest"}}}},"responses":{"201":{"description":"AI conversation created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiConversationEnvelope"}}}}}}},"/ai/visitor/chat":{"post":{"tags":["AI"],"operationId":"sendAiVisitorMessage","summary":"Send a visitor AI chat message.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiChatRequest"}}}},"responses":{"200":{"description":"AI response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiChatEnvelope"}}}}}}},"/ai/visitor/knowledge/search":{"post":{"tags":["AI"],"operationId":"searchAiVisitorKnowledge","summary":"Search AI knowledge for the visitor context.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSearchRequest"}}}},"responses":{"200":{"description":"Knowledge search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSearchEnvelope"}}}}}}},"/ai/visitor/realtime/call":{"post":{"tags":["AI"],"operationId":"createAiVisitorRealtimeCall","summary":"Create an AI voice call realtime session.","description":"Low-level transport body is kept behind SDK call objects for normal customers.","security":[{"RuntimeBearer":[]},{}],"requestBody":{"required":true,"content":{"application/sdp":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Realtime answer.","content":{"application/sdp":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}}}}},"/.well-known/openid-configuration":{"servers":[{"url":"https://api.ringnity.com","description":"Production identity issuer"},{"url":"http://localhost:8192","description":"Local identity issuer"}],"get":{"tags":["Login with Ringnity"],"operationId":"getOpenIdConfiguration","summary":"Read OpenID Connect discovery metadata.","description":"Root-level discovery document for apps that implement Login with Ringnity.","responses":{"200":{"description":"OpenID Connect discovery metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenIdConfiguration"}}}}}}},"/oauth/authorize":{"servers":[{"url":"https://api.ringnity.com","description":"Production identity issuer"},{"url":"http://localhost:8192","description":"Local identity issuer"}],"get":{"tags":["Login with Ringnity"],"operationId":"authorizeWithRingnity","summary":"Start Login with Ringnity authorization.","description":"Authorization Code Flow endpoint for CMS, CRM, web apps, and mobile apps using PKCE.","parameters":[{"name":"response_type","in":"query","required":true,"schema":{"type":"string","enum":["code"]}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string","format":"uri"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","example":"openid profile email tenant.read roles.read developer.read"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}},{"name":"nonce","in":"query","schema":{"type":"string"}},{"name":"code_challenge","in":"query","schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","schema":{"type":"string","enum":["S256","plain"]}}],"responses":{"302":{"description":"Redirect back to the registered callback URL with code or error parameters.","headers":{"Location":{"schema":{"type":"string","format":"uri"}}}},"503":{"$ref":"#/components/responses/OAuthErrorResponse"},"4XX":{"$ref":"#/components/responses/OAuthErrorResponse"}}}},"/oauth/token":{"servers":[{"url":"https://api.ringnity.com","description":"Production identity issuer"},{"url":"http://localhost:8192","description":"Local identity issuer"}],"post":{"tags":["Login with Ringnity"],"operationId":"exchangeRingnityOAuthToken","summary":"Exchange authorization code or refresh token.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/OAuthTokenRequest"}}}},"responses":{"200":{"description":"OAuth/OIDC token response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenResponse"}}}},"503":{"$ref":"#/components/responses/OAuthErrorResponse"},"4XX":{"$ref":"#/components/responses/OAuthErrorResponse"}}}},"/oauth/userinfo":{"servers":[{"url":"https://api.ringnity.com","description":"Production identity issuer"},{"url":"http://localhost:8192","description":"Local identity issuer"}],"get":{"tags":["Login with Ringnity"],"operationId":"getRingnityOAuthUserInfo","summary":"Read OIDC user profile claims.","security":[{"OAuthAccessToken":[]}],"responses":{"200":{"description":"UserInfo claims for the logged-in Ringnity user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthUserInfo"}}}},"503":{"$ref":"#/components/responses/OAuthErrorResponse"},"4XX":{"$ref":"#/components/responses/OAuthErrorResponse"}}}},"/oauth/tenant/widget-key":{"servers":[{"url":"https://api.ringnity.com","description":"Production identity issuer"},{"url":"http://localhost:8192","description":"Local identity issuer"}],"get":{"tags":["Login with Ringnity"],"operationId":"getRingnityOAuthWidgetKey","summary":"Read the public Website widget install key for the OAuth tenant.","description":"Requires an OAuth access token with `developer.read` or `sdk.keys.read`. The returned key is used for direct visitor app links, WordPress auto widget installs, and the universal widget script.","security":[{"OAuthAccessToken":[]}],"responses":{"200":{"description":"Public Website widget install key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthWidgetKeyEnvelope"}}}},"503":{"$ref":"#/components/responses/OAuthErrorResponse"},"4XX":{"$ref":"#/components/responses/OAuthErrorResponse"}}}},"/oauth/tenant/allowed-domains":{"servers":[{"url":"https://api.ringnity.com","description":"Production identity issuer"},{"url":"http://localhost:8192","description":"Local identity issuer"}],"post":{"tags":["Login with Ringnity"],"operationId":"addRingnityOAuthAllowedDomain","summary":"Add one allowed Website widget domain for the OAuth tenant.","description":"Requires an OAuth access token with `tenant.domains.write`. The backend enforces the tenant plan quota `allowed_domains`.","security":[{"OAuthAccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthAddAllowedDomainRequest"}}}},"responses":{"200":{"description":"Domain was added or was already allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthWidgetKeyEnvelope"}}}},"409":{"$ref":"#/components/responses/OAuthErrorResponse"},"503":{"$ref":"#/components/responses/OAuthErrorResponse"},"4XX":{"$ref":"#/components/responses/OAuthErrorResponse"}}}},"/oauth/jwks.json":{"servers":[{"url":"https://api.ringnity.com","description":"Production identity issuer"},{"url":"http://localhost:8192","description":"Local identity issuer"}],"get":{"tags":["Login with Ringnity"],"operationId":"getRingnityOAuthJwks","summary":"Read public keys for ID token verification.","responses":{"200":{"description":"JSON Web Key Set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Jwks"}}}}}}},"/oauth/revoke":{"servers":[{"url":"https://api.ringnity.com","description":"Production identity issuer"},{"url":"http://localhost:8192","description":"Local identity issuer"}],"post":{"tags":["Login with Ringnity"],"operationId":"revokeRingnityOAuthToken","summary":"Revoke an OAuth refresh token or access token.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/OAuthRevokeRequest"}}}},"responses":{"200":{"description":"Token revoke request accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"503":{"$ref":"#/components/responses/OAuthErrorResponse"},"4XX":{"$ref":"#/components/responses/OAuthErrorResponse"}}}}},"components":{"securitySchemes":{"ServerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Ringnity Server API Key","description":"Secret Server API key. Must only be used from customer-owned backend servers."},"RuntimeBearer":{"type":"apiKey","in":"header","name":"X-Ringnity-SDK-Session","description":"Short-lived SDK runtime token issued by `/sdk/session`."},"DashboardBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Logged-in Ringnity owner or workspace dashboard JWT."},"OwnerBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Owner JWT with internal `scope: owner`, issued by `/auth/owner-login` or `/auth/owner-refresh`."},"WorkspaceBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Workspace JWT with internal `scope: workspace`, issued by `/auth/workspace-login`, `/auth/workspace-auto-login`, or `/auth/workspace-refresh`."},"PlatformBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Platform admin JWT issued by `/platform/auth/login`."},"OAuthAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 access token issued by Login with Ringnity."}},"parameters":{"TenantSlugQuery":{"name":"slug","in":"query","schema":{"type":"string","example":"your-tenant-slug"},"description":"Public tenant slug."},"PublicKeyQuery":{"name":"apiKey","in":"query","schema":{"type":"string"},"description":"Public widget/install key for legacy compatibility."},"DebugQuery":{"name":"debug","in":"query","schema":{"type":"boolean"},"description":"Include blocked-service reasons for developer diagnostics."},"PageQuery":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"LimitQuery":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"CursorQuery":{"name":"cursor","in":"query","schema":{"type":"string"}},"ReportPeriodQuery":{"name":"period","in":"query","description":"Preset reporting range. Use custom together with startDate and endDate.","schema":{"type":"string","enum":["today","7days","30days","custom"],"default":"today"}},"ReportStartDateQuery":{"name":"startDate","in":"query","description":"ISO date or date-time. Required when period is custom.","schema":{"type":"string","format":"date-time"}},"ReportEndDateQuery":{"name":"endDate","in":"query","description":"ISO date or date-time. Required when period is custom.","schema":{"type":"string","format":"date-time"}},"ReportAgentIdQuery":{"name":"agentId","in":"query","description":"Optional agent ID filter for productivity reports.","schema":{"type":"string"}},"ReportFormatQuery":{"name":"format","in":"query","description":"Export format.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},"CredentialIdPath":{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"}},"OAuthClientIdPath":{"name":"oauthClientId","in":"path","required":true,"schema":{"type":"string"}},"ClientIdPath":{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},"ContactIdPath":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"WebhookIdPath":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"ConversationIdPath":{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}},"MessageIdPath":{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}},"CallSessionIdPath":{"name":"callSessionId","in":"path","required":true,"schema":{"type":"string"}},"KnowledgeItemIdPath":{"name":"knowledgeItemId","in":"path","required":true,"schema":{"type":"string"}}},"responses":{"ErrorResponse":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"OAuthErrorResponse":{"description":"OAuth2/OIDC error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}},"schemas":{"AnyObject":{"type":"object","additionalProperties":true},"RefreshTokenRequest":{"type":"object","properties":{"refreshToken":{"type":"string"}}},"OwnerLoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","format":"password"}}},"OwnerGoogleLoginRequest":{"type":"object","required":["idToken"],"properties":{"idToken":{"type":"string","description":"Google Identity Services ID token."}}},"OwnerClient":{"type":"object","required":["id","email","slug","isActive","onboardingCompleted","apiKey"],"properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string","format":"email"},"slug":{"type":"string"},"companyName":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"industry":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"onboardingCompleted":{"type":"boolean"},"apiKey":{"type":"string"}}},"OwnerAdmin":{"type":"object","required":["agentId","username","name"],"properties":{"agentId":{"type":"string"},"username":{"type":"string"},"name":{"type":"string"}}},"OwnerSubscription":{"type":"object","required":["planName","planSlug","status"],"properties":{"planName":{"type":"string"},"planSlug":{"type":"string"},"status":{"type":"string"}}},"OwnerSession":{"type":"object","required":["client","subscription","accessToken","refreshToken","expiresIn","dashboardUrl"],"properties":{"client":{"$ref":"#/components/schemas/OwnerClient"},"admin":{"anyOf":[{"$ref":"#/components/schemas/OwnerAdmin"},{"type":"null"}]},"subscription":{"$ref":"#/components/schemas/OwnerSubscription"},"accessToken":{"type":"string","description":"Owner JWT with internal `scope: owner`."},"refreshToken":{"type":"string"},"expiresIn":{"type":"integer"},"sessionToken":{"type":"string","deprecated":true,"description":"Deprecated alias of `accessToken`."},"dashboardUrl":{"type":"string","format":"uri"}}},"OwnerSessionEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/OwnerSession"}}},"OwnerMeEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["client","subscription","dashboardUrl"],"properties":{"client":{"$ref":"#/components/schemas/OwnerClient"},"admin":{"anyOf":[{"$ref":"#/components/schemas/OwnerAdmin"},{"type":"null"}]},"subscription":{"$ref":"#/components/schemas/OwnerSubscription"},"dashboardUrl":{"type":"string","format":"uri"}}}}},"OwnerRefreshEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["accessToken","refreshToken","expiresIn"],"properties":{"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresIn":{"type":"integer"},"sessionToken":{"type":"string","deprecated":true,"description":"Deprecated alias of `accessToken`."}}}}},"OwnerGoogleLoginEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["requiresRegistration"],"properties":{"requiresRegistration":{"type":"boolean"},"client":{"$ref":"#/components/schemas/OwnerClient"},"admin":{"anyOf":[{"$ref":"#/components/schemas/OwnerAdmin"},{"type":"null"}]},"subscription":{"$ref":"#/components/schemas/OwnerSubscription"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresIn":{"type":"integer"},"sessionToken":{"type":"string","deprecated":true},"dashboardUrl":{"type":"string","format":"uri"},"googleProfile":{"$ref":"#/components/schemas/AnyObject"}}}}},"WorkspaceLoginRequest":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string"},"password":{"type":"string","format":"password"}}},"WorkspaceRole":{"type":"string","enum":["owner","admin","supervisor","agent"]},"WorkspaceAgent":{"type":"object","required":["agentId","username","name","isOwner","isAdmin","role","clientId","clientSlug"],"properties":{"agentId":{"type":"string"},"username":{"type":"string"},"name":{"type":"string"},"isOwner":{"type":"boolean"},"isAdmin":{"type":"boolean"},"role":{"$ref":"#/components/schemas/WorkspaceRole"},"clientId":{"type":"string"},"clientSlug":{"type":"string"},"profileImage":{"type":"string","nullable":true},"typeCall":{"type":"string","nullable":true},"department":{"$ref":"#/components/schemas/AnyObject"},"position":{"$ref":"#/components/schemas/AnyObject"}}},"WorkspaceSession":{"type":"object","required":["accessToken","refreshToken","expiresIn"],"properties":{"accessToken":{"type":"string","description":"Workspace JWT with internal `scope: workspace`."},"refreshToken":{"type":"string"},"expiresIn":{"type":"integer"},"token":{"type":"string","deprecated":true,"description":"Deprecated alias of `accessToken`."},"agent":{"$ref":"#/components/schemas/WorkspaceAgent"},"agentId":{"type":"string"},"username":{"type":"string"},"name":{"type":"string"}}},"WorkspaceSessionEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/WorkspaceSession"}}},"WorkspaceAutoLoginEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"allOf":[{"$ref":"#/components/schemas/WorkspaceSession"},{"type":"object","required":["agent"]}]}}},"WorkspaceRefreshEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["accessToken","refreshToken","expiresIn"],"properties":{"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresIn":{"type":"integer"}}}}},"WorkspaceEntryTokenEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["autoLoginToken","dashboardUrl","expiresIn"],"properties":{"autoLoginToken":{"type":"string"},"dashboardUrl":{"type":"string","format":"uri"},"expiresIn":{"type":"integer"}}}}},"PlatformRole":{"type":"string","enum":["platform_owner","platform_admin","platform_support"]},"PlatformLoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"admin@ringnity.test"},"password":{"type":"string","format":"password"}}},"PlatformRefreshRequest":{"type":"object","required":["refreshToken"],"properties":{"refreshToken":{"type":"string","description":"Refresh token returned by platform login or the previous refresh call."}}},"PlatformSession":{"type":"object","required":["adminId","email","name","role","accessToken","refreshToken","expiresIn"],"properties":{"adminId":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"$ref":"#/components/schemas/PlatformRole"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresIn":{"type":"integer","description":"Access token lifetime in seconds."}}},"PlatformSessionEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/PlatformSession"}}},"PlanContractValueType":{"type":"string","enum":["number","unlimited","custom","disabled"]},"PlanContractFeatureKey":{"type":"object","required":["featureKey","name","category","description","status","sortOrder"],"properties":{"featureKey":{"type":"string","example":"video"},"name":{"type":"string","example":"Video"},"category":{"type":"string","example":"communication"},"description":{"type":"string","example":"Visitor video calls and video escalation."},"status":{"type":"string","example":"stable"},"sortOrder":{"type":"integer","example":30}}},"PlanContractQuotaKey":{"type":"object","required":["quotaKey","name","unit","category","description","sortOrder"],"properties":{"quotaKey":{"type":"string","example":"agents"},"name":{"type":"string","example":"Agents"},"unit":{"type":"string","example":"agent"},"category":{"type":"string","example":"core"},"description":{"type":"string","example":"Non-owner agent accounts allowed by the plan."},"sortOrder":{"type":"integer","example":10}}},"PlanFeatureContract":{"type":"object","required":["enabled"],"properties":{"planId":{"type":"string"},"featureKey":{"type":"string"},"enabled":{"type":"boolean"},"config":{"$ref":"#/components/schemas/AnyObject"}}},"PlanQuotaContract":{"type":"object","required":["valueType"],"properties":{"planId":{"type":"string"},"quotaKey":{"type":"string"},"valueType":{"$ref":"#/components/schemas/PlanContractValueType"},"limitValue":{"type":"integer","nullable":true,"description":"Numeric limit when `valueType` is `number`; null otherwise."},"resetPeriod":{"type":"string","nullable":true,"example":"monthly"},"config":{"$ref":"#/components/schemas/AnyObject"}}},"PlanContractPlan":{"type":"object","required":["planId","slug","name","sortOrder","isActive","features","quotas"],"properties":{"planId":{"type":"string"},"slug":{"type":"string","example":"professional"},"name":{"type":"string","example":"Professional"},"sortOrder":{"type":"integer"},"isActive":{"type":"boolean"},"features":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/PlanFeatureContract"}},"quotas":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/PlanQuotaContract"}}}},"PlanContractCatalog":{"type":"object","required":["featureKeys","quotaKeys","plans"],"properties":{"featureKeys":{"type":"array","items":{"$ref":"#/components/schemas/PlanContractFeatureKey"}},"quotaKeys":{"type":"array","items":{"$ref":"#/components/schemas/PlanContractQuotaKey"}},"plans":{"type":"array","items":{"$ref":"#/components/schemas/PlanContractPlan"}}}},"PlanContractCatalogEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/PlanContractCatalog"},"message":{"type":"string"}}},"AiPricingSettings":{"type":"object","required":["provider","currency","chatModel","voiceModel","inputCostPer1mUsd","cachedInputCostPer1mUsd","outputCostPer1mUsd","voiceCostPerMinuteUsd","markupMultiplier","riskBufferPercent","replyUnitInputTokens","replyUnitOutputTokens","voiceUnitSeconds","maxInputTokens","maxOutputTokens","maxContextMessages","maxKnowledgeChunks","maxRetries","maxToolCalls","dailySpendLimitCents","monthlySpendLimitCents","lowBalanceThresholdCents"],"properties":{"provider":{"type":"string","example":"openai"},"currency":{"type":"string","example":"USD"},"chatModel":{"type":"string","example":"gpt-4.1-mini"},"voiceModel":{"type":"string","example":"gpt-realtime"},"inputCostPer1mUsd":{"type":"number","example":0.4},"cachedInputCostPer1mUsd":{"type":"number","example":0.1},"outputCostPer1mUsd":{"type":"number","example":1.6},"voiceCostPerMinuteUsd":{"type":"number","example":0.03},"markupMultiplier":{"type":"number","minimum":1.1,"example":3},"riskBufferPercent":{"type":"number","minimum":0,"example":25},"replyUnitInputTokens":{"type":"integer","minimum":0,"example":3000},"replyUnitOutputTokens":{"type":"integer","minimum":0,"example":1000},"voiceUnitSeconds":{"type":"integer","minimum":1,"example":60},"maxInputTokens":{"type":"integer","minimum":0,"example":12000},"maxOutputTokens":{"type":"integer","minimum":0,"example":1500},"maxContextMessages":{"type":"integer","minimum":0,"example":12},"maxKnowledgeChunks":{"type":"integer","minimum":0,"example":6},"maxRetries":{"type":"integer","minimum":0,"example":1},"maxToolCalls":{"type":"integer","minimum":0,"example":4},"dailySpendLimitCents":{"type":"integer","minimum":0,"example":5000},"monthlySpendLimitCents":{"type":"integer","minimum":0,"example":50000},"lowBalanceThresholdCents":{"type":"integer","minimum":0,"example":1000},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"AiPricingSettingsUpdate":{"type":"object","description":"Partial AI pricing settings update. Omitted fields keep their current value.","properties":{"provider":{"type":"string"},"currency":{"type":"string"},"chatModel":{"type":"string"},"voiceModel":{"type":"string"},"inputCostPer1mUsd":{"type":"number"},"cachedInputCostPer1mUsd":{"type":"number"},"outputCostPer1mUsd":{"type":"number"},"voiceCostPerMinuteUsd":{"type":"number"},"markupMultiplier":{"type":"number","minimum":1.1},"riskBufferPercent":{"type":"number","minimum":0},"replyUnitInputTokens":{"type":"integer","minimum":0},"replyUnitOutputTokens":{"type":"integer","minimum":0},"voiceUnitSeconds":{"type":"integer","minimum":1},"maxInputTokens":{"type":"integer","minimum":0},"maxOutputTokens":{"type":"integer","minimum":0},"maxContextMessages":{"type":"integer","minimum":0},"maxKnowledgeChunks":{"type":"integer","minimum":0},"maxRetries":{"type":"integer","minimum":0},"maxToolCalls":{"type":"integer","minimum":0},"dailySpendLimitCents":{"type":"integer","minimum":0},"monthlySpendLimitCents":{"type":"integer","minimum":0},"lowBalanceThresholdCents":{"type":"integer","minimum":0}}},"AiPricingDerived":{"type":"object","required":["internalReplyUsd","retailReplyUsd","retailPer1000RepliesUsd","internalVoiceMinuteUsd","retailVoiceMinuteUsd","grossMarginPercent"],"properties":{"internalReplyUsd":{"type":"number"},"retailReplyUsd":{"type":"number"},"retailPer1000RepliesUsd":{"type":"number"},"internalVoiceMinuteUsd":{"type":"number"},"retailVoiceMinuteUsd":{"type":"number"},"grossMarginPercent":{"type":"number","example":66.7}}},"AiPricingCatalog":{"type":"object","required":["settings","derived"],"properties":{"settings":{"$ref":"#/components/schemas/AiPricingSettings"},"derived":{"$ref":"#/components/schemas/AiPricingDerived"}}},"AiPricingCatalogEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AiPricingCatalog"},"message":{"type":"string"}}},"AiBillingAlertLevel":{"type":"string","enum":["ok","low","critical","empty"]},"AiBalanceSummary":{"type":"object","required":["totalTenants","totalBalanceCents","totalEstimatedOverageCents","totalEstimatedRetailChargeCents","totalEstimatedInternalCostCents","totalChatReplies","totalVoiceMinutes","emptyCount","criticalCount","lowCount"],"properties":{"totalTenants":{"type":"integer"},"totalBalanceCents":{"type":"integer"},"totalEstimatedOverageCents":{"type":"integer"},"totalEstimatedRetailChargeCents":{"type":"integer"},"totalEstimatedInternalCostCents":{"type":"integer"},"totalChatReplies":{"type":"integer"},"totalVoiceMinutes":{"type":"integer"},"emptyCount":{"type":"integer"},"criticalCount":{"type":"integer"},"lowCount":{"type":"integer"}}},"AiTenantUsage":{"type":"object","required":["chatReplies","voiceMinutes","voiceEvents","audioSeconds","inputTokens","outputTokens","totalTokens"],"properties":{"chatReplies":{"type":"integer"},"voiceMinutes":{"type":"integer"},"voiceEvents":{"type":"integer"},"audioSeconds":{"type":"integer"},"inputTokens":{"type":"integer"},"outputTokens":{"type":"integer"},"totalTokens":{"type":"integer"}}},"AiTenantIncludedQuota":{"type":"object","required":["chatLabel","voiceLabel"],"properties":{"chatReplies":{"type":"integer","nullable":true,"description":"Null means custom or unlimited plan handling."},"chatLabel":{"type":"string","example":"5,000 replies"},"voiceMinutes":{"type":"integer","nullable":true,"description":"Null means custom or unlimited plan handling."},"voiceLabel":{"type":"string","example":"300 minutes"}}},"AiTenantOverage":{"type":"object","required":["chatReplies","voiceMinutes","estimatedInternalCostCents","estimatedRetailChargeCents","estimatedOverageChargeCents","projectedBalanceAfterCents"],"properties":{"chatReplies":{"type":"integer"},"voiceMinutes":{"type":"integer"},"estimatedInternalCostCents":{"type":"integer"},"estimatedRetailChargeCents":{"type":"integer"},"estimatedOverageChargeCents":{"type":"integer"},"projectedBalanceAfterCents":{"type":"integer"}}},"AiTenantBalance":{"type":"object","required":["tenantId","tenantName","tenantEmail","tenantSlug","planSlug","planName","currency","balanceCents","totalTopUpCents","totalUsageCents","overageEnabled","blockOnZero","autoTopUpEnabled","autoTopUpThresholdCents","autoTopUpAmountCents","usage","included","overage","alertLevel"],"properties":{"tenantId":{"type":"string"},"tenantName":{"type":"string"},"tenantEmail":{"type":"string","format":"email"},"tenantSlug":{"type":"string"},"planId":{"type":"string","nullable":true},"planSlug":{"type":"string"},"planName":{"type":"string"},"currency":{"type":"string","example":"USD"},"balanceCents":{"type":"integer"},"totalTopUpCents":{"type":"integer"},"totalUsageCents":{"type":"integer"},"overageEnabled":{"type":"boolean"},"blockOnZero":{"type":"boolean"},"autoTopUpEnabled":{"type":"boolean"},"autoTopUpThresholdCents":{"type":"integer"},"autoTopUpAmountCents":{"type":"integer"},"lastTopUpAt":{"type":"string","format":"date-time","nullable":true},"usage":{"$ref":"#/components/schemas/AiTenantUsage"},"included":{"$ref":"#/components/schemas/AiTenantIncludedQuota"},"overage":{"$ref":"#/components/schemas/AiTenantOverage"},"alertLevel":{"$ref":"#/components/schemas/AiBillingAlertLevel"}}},"AiBalanceOverview":{"type":"object","required":["summary","tenants","pricing","checkedAt"],"properties":{"summary":{"$ref":"#/components/schemas/AiBalanceSummary"},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/AiTenantBalance"}},"pricing":{"$ref":"#/components/schemas/AiPricingCatalog"},"checkedAt":{"type":"string","format":"date-time"}}},"AiBalanceOverviewEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AiBalanceOverview"}}},"AiBalanceTopUpRequest":{"type":"object","properties":{"amountCents":{"type":"integer","minimum":1,"description":"Top-up amount in cents. Preferred over amountUsd.","example":5000},"amountUsd":{"type":"number","minimum":0,"description":"Legacy convenience amount. The server converts it to cents.","example":50},"notes":{"type":"string","maxLength":500}}},"AiBalanceTopUpResult":{"type":"object","required":["clientId","amountCents","balanceBeforeCents","balanceAfterCents"],"properties":{"clientId":{"type":"string"},"amountCents":{"type":"integer"},"balanceBeforeCents":{"type":"integer"},"balanceAfterCents":{"type":"integer"}}},"AiBalanceTopUpEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AiBalanceTopUpResult"},"message":{"type":"string"}}},"AiBalanceTenantSettingsRequest":{"type":"object","properties":{"overageEnabled":{"type":"boolean"},"blockOnZero":{"type":"boolean"},"autoTopUpEnabled":{"type":"boolean"},"autoTopUpThresholdCents":{"type":"integer","minimum":0},"autoTopUpAmountCents":{"type":"integer","minimum":0}}},"AiBalanceTenantSettingsResult":{"type":"object","required":["clientId"],"properties":{"clientId":{"type":"string"}}},"AiBalanceTenantSettingsEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AiBalanceTenantSettingsResult"},"message":{"type":"string"}}},"OAuthScope":{"type":"string","description":"Known OAuth scope name. Only scopes marked `available` in `scopeCatalog` can be selected for new OAuth clients.","enum":["openid","profile","email","offline_access","user.profile.read","user.profile.write","user.avatar.read","user.avatar.write","tenant.read","tenant.profile.read","tenant.profile.write","tenant.branding.read","tenant.branding.write","tenant.settings.read","tenant.settings.write","tenant.domains.read","tenant.domains.write","roles.read","staff.read","staff.write","staff.invite","staff.disable","runtime.tokens.write","runtime.sessions.read","runtime.sessions.write","agents.read","agents.write","agents.presence.read","agents.presence.write","contacts.read","contacts.write","contacts.delete","conversations.read","conversations.write","conversations.assign","conversations.close","calls.read","calls.write","calls.recordings.read","calls.recordings.delete","ai.read","ai.write","ai.knowledge.read","ai.knowledge.write","ai.usage.read","reports.read","reports.export","webhooks.read","webhooks.write","webhooks.delete","webhooks.test","developer.read","developer.write","sdk.keys.read","sdk.keys.write","oauth.clients.read","oauth.clients.write","media.read","media.write","media.delete","billing.read","billing.write"]},"OAuthScopeStatus":{"type":"string","enum":["available","planned"]},"OAuthScopeCatalogItem":{"type":"object","required":["scope","category","status","sensitive","description"],"properties":{"scope":{"$ref":"#/components/schemas/OAuthScope"},"category":{"type":"string","example":"Tenant / Business"},"status":{"$ref":"#/components/schemas/OAuthScopeStatus"},"sensitive":{"type":"boolean"},"description":{"type":"string"}}},"OAuthClientType":{"type":"string","enum":["confidential","public"]},"OAuthClientStatus":{"type":"string","enum":["active","revoked"]},"OAuthClient":{"type":"object","required":["id","clientId","name","type","status","allowedScopes","redirectUris","requirePkce"],"properties":{"id":{"type":"string"},"clientId":{"type":"string","example":"rn_oauth_xxxxxxxxxxxxxxxxxxxxxxxx"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/OAuthClientType"},"status":{"$ref":"#/components/schemas/OAuthClientStatus"},"allowedScopes":{"type":"array","items":{"$ref":"#/components/schemas/OAuthScope"}},"redirectUris":{"type":"array","items":{"type":"string","format":"uri"}},"requirePkce":{"type":"boolean"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"OAuthClientEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["oauthClient"],"properties":{"oauthClient":{"$ref":"#/components/schemas/OAuthClient"}}}}},"OAuthClientListEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["oauthClients","availableScopes","recommendedScopes","scopeCatalog","clientTypes","discoveryUrl"],"properties":{"oauthClients":{"type":"array","items":{"$ref":"#/components/schemas/OAuthClient"}},"availableScopes":{"description":"Scopes selectable for OAuth clients today.","type":"array","items":{"$ref":"#/components/schemas/OAuthScope"}},"recommendedScopes":{"type":"array","items":{"$ref":"#/components/schemas/OAuthScope"}},"scopeCatalog":{"description":"Full ideal scope catalog. Planned scopes are shown disabled in UI until matching APIs are ready.","type":"array","items":{"$ref":"#/components/schemas/OAuthScopeCatalogItem"}},"clientTypes":{"type":"array","items":{"$ref":"#/components/schemas/OAuthClientType"}},"discoveryUrl":{"type":"string","format":"uri"}}}}},"OAuthClientSecretEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["oauthClient","warning"],"properties":{"oauthClient":{"$ref":"#/components/schemas/OAuthClient"},"clientSecret":{"type":"string","description":"Returned once for confidential clients."},"warning":{"type":"string"}}}}},"OAuthClientDeletedEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["oauthClientId","deleted"],"properties":{"oauthClientId":{"type":"string"},"deleted":{"type":"boolean","const":true}}}}},"CreateOAuthClientRequest":{"type":"object","required":["name","redirectUris"],"properties":{"name":{"type":"string","maxLength":120},"type":{"$ref":"#/components/schemas/OAuthClientType"},"redirectUris":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"}},"allowedScopes":{"type":"array","items":{"$ref":"#/components/schemas/OAuthScope"},"default":["openid","profile","email","tenant.read","roles.read","developer.read","tenant.domains.read","tenant.domains.write"]},"requirePkce":{"type":"boolean","description":"Required for public/native clients. Optional for confidential CMS clients."}}},"UpdateOAuthClientRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"type":{"$ref":"#/components/schemas/OAuthClientType"},"status":{"$ref":"#/components/schemas/OAuthClientStatus"},"redirectUris":{"type":"array","items":{"type":"string","format":"uri"}},"allowedScopes":{"type":"array","items":{"$ref":"#/components/schemas/OAuthScope"}},"requirePkce":{"type":"boolean"}}},"OpenIdConfiguration":{"type":"object","required":["issuer","authorization_endpoint","token_endpoint","userinfo_endpoint","jwks_uri","response_types_supported","subject_types_supported","id_token_signing_alg_values_supported","scopes_supported","token_endpoint_auth_methods_supported","claims_supported"],"properties":{"issuer":{"type":"string","format":"uri","example":"https://api.ringnity.com"},"authorization_endpoint":{"type":"string","format":"uri","example":"https://api.ringnity.com/oauth/authorize"},"token_endpoint":{"type":"string","format":"uri","example":"https://api.ringnity.com/oauth/token"},"userinfo_endpoint":{"type":"string","format":"uri","example":"https://api.ringnity.com/oauth/userinfo"},"jwks_uri":{"type":"string","format":"uri","example":"https://api.ringnity.com/oauth/jwks.json"},"revocation_endpoint":{"type":"string","format":"uri","example":"https://api.ringnity.com/oauth/revoke"},"response_types_supported":{"type":"array","items":{"type":"string"},"example":["code"]},"subject_types_supported":{"type":"array","items":{"type":"string"},"example":["public"]},"id_token_signing_alg_values_supported":{"type":"array","items":{"type":"string"},"example":["RS256"]},"scopes_supported":{"type":"array","items":{"$ref":"#/components/schemas/OAuthScope"},"example":["openid","profile","email","tenant.read","roles.read","tenant.domains.read","tenant.domains.write","developer.read","sdk.keys.read"]},"token_endpoint_auth_methods_supported":{"type":"array","items":{"type":"string"},"example":["client_secret_basic","client_secret_post","none"]},"code_challenge_methods_supported":{"type":"array","items":{"type":"string"},"example":["S256"]},"claims_supported":{"type":"array","items":{"type":"string"},"example":["sub","name","email","tenant_id","tenant_slug","roles"]}}},"OAuthTokenRequest":{"type":"object","required":["grant_type","client_id"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"client_id":{"type":"string"},"client_secret":{"type":"string","description":"Required for confidential clients. Never used by public/native clients."},"code":{"type":"string","description":"Required when grant_type is authorization_code."},"redirect_uri":{"type":"string","format":"uri","description":"Must exactly match the authorize request redirect URI."},"code_verifier":{"type":"string","description":"Required for PKCE clients."},"refresh_token":{"type":"string","description":"Required when grant_type is refresh_token."}}},"OAuthTokenResponse":{"type":"object","required":["access_token","token_type","expires_in"],"properties":{"access_token":{"type":"string"},"id_token":{"type":"string","description":"OIDC ID token returned when the openid scope is granted."},"refresh_token":{"type":"string"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","example":900},"scope":{"type":"string","example":"openid profile email tenant.read roles.read"}}},"OAuthUserInfo":{"type":"object","required":["sub"],"properties":{"sub":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"email_verified":{"type":"boolean"},"tenant_id":{"type":"string"},"tenant_slug":{"type":"string","example":"your-tenant-slug"},"roles":{"type":"array","items":{"type":"string"}}}},"OAuthWidgetKeyEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["tenantId","tenantSlug","publicWidgetKey"],"properties":{"tenantId":{"type":"string"},"tenantSlug":{"type":"string","example":"your-tenant-slug"},"publicWidgetKey":{"type":"string","description":"Public Website widget/install key safe for direct visitor app links, WordPress auto widget installs, and universal widget bootstrap."},"allowedDomains":{"type":"array","items":{"type":"string"}},"allowedDomainsLimit":{"type":"integer","nullable":true,"description":"Maximum domains allowed by the current plan. Null means unlimited."},"allowedDomainsUsed":{"type":"integer","description":"Number of configured allowed domains."},"allowedDomainsRemaining":{"type":"integer","nullable":true,"description":"Remaining domains before hitting the current plan quota. Null means unlimited."},"dashboardDeveloperUrl":{"type":"string","format":"uri","description":"Tenant dashboard URL for manual allowed-domain management."},"domain":{"type":"string","description":"Domain submitted to the add-domain endpoint, when present."},"domainAdded":{"type":"boolean","description":"True when the submitted domain was added by this request."},"domainAlreadyAllowed":{"type":"boolean","description":"True when the submitted domain was already covered by the allowed-domain list."}}}}},"OAuthAddAllowedDomainRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"wordpress.example.com"}}},"Jwk":{"type":"object","required":["kty","kid","use","alg","n","e"],"properties":{"kty":{"type":"string","example":"RSA"},"kid":{"type":"string"},"use":{"type":"string","example":"sig"},"alg":{"type":"string","example":"RS256"},"n":{"type":"string"},"e":{"type":"string"}}},"Jwks":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/Jwk"}}}},"OAuthRevokeRequest":{"type":"object","required":["token","client_id"],"properties":{"token":{"type":"string"},"token_type_hint":{"type":"string","enum":["access_token","refresh_token"]},"client_id":{"type":"string"},"client_secret":{"type":"string","description":"Required for confidential clients."}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_request","invalid_client","invalid_grant","unauthorized_client","unsupported_grant_type","invalid_scope","temporarily_unavailable"]},"error_description":{"type":"string"},"state":{"type":"string"}}},"ErrorEnvelope":{"type":"object","required":["success","code","message"],"properties":{"success":{"type":"boolean","const":false},"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}},"detail":{"$ref":"#/components/schemas/AnyObject"}}},"ErrorCode":{"type":"string","enum":["SDK_CLIENT_NOT_FOUND","SDK_CLIENT_INACTIVE","SDK_ORIGIN_NOT_ALLOWED","SDK_CONTEXT_TOKEN_INVALID","SDK_BOOTSTRAP_FAILED","SDK_SESSION_FAILED","SDK_SESSION_REQUIRED","SDK_DEVICE_TOKEN_INVALID","SDK_DEVICE_TOKEN_REGISTER_FAILED","SDK_DEVICE_TOKEN_UNREGISTER_FAILED","SDK_VERSION_UNSUPPORTED","FEATURE_NOT_AVAILABLE","SERVER_API_KEY_INVALID","SERVER_API_CONTEXT_MISSING","SERVER_API_SCOPE_DENIED","SERVER_CONTACT_VALIDATION_FAILED","SERVER_WEBHOOK_VALIDATION_FAILED","SERVER_WEBHOOK_NOT_FOUND","SERVER_API_REPORTS_FAILED","ADMIN_SDK_REPORTS_FAILED","REPORT_DATE_RANGE_INVALID","TOKEN_EXPIRED","RATE_LIMITED","NETWORK_ERROR","NETWORK_UNAVAILABLE","REALTIME_DISCONNECTED","CALL_PERMISSION_DENIED","CALL_SESSION_CONVERSATION_REQUIRED","CALL_SESSION_TYPE_INVALID","CALL_SESSION_NOT_FOUND","CALL_SESSION_CREATE_FAILED","CALL_SESSION_READ_FAILED","CALL_SESSION_END_FAILED","AI_NOT_READY"]},"SuccessEnvelope":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnyObject"}}},"Tenant":{"type":"object","required":["clientId"],"properties":{"clientId":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"companyName":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"timezone":{"type":"string"},"isActive":{"type":"boolean"}}},"TenantEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/Tenant"}}}}},"ServiceStatus":{"type":"string","enum":["available","disabled_by_admin","not_in_plan","not_configured","ai_not_ready","beta"]},"ServiceKey":{"type":"string","enum":["chat","voice_call","video_call","ai_chat","ai_voice","ai_video"]},"ServiceCapability":{"type":"object","required":["key","status"],"properties":{"key":{"$ref":"#/components/schemas/ServiceKey"},"label":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"allowed":{"type":"boolean"},"reason":{"type":"string"},"requiredFeatures":{"type":"array","items":{"type":"string"}},"adminEnabled":{"type":"boolean"},"sortOrder":{"type":"integer"}}},"RuntimeBootstrap":{"type":"object","required":["tenant","services"],"properties":{"tenant":{"$ref":"#/components/schemas/Tenant"},"branding":{"$ref":"#/components/schemas/AnyObject"},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCapability"}},"sdk":{"$ref":"#/components/schemas/AnyObject"}}},"RuntimeBootstrapEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/RuntimeBootstrap"}}},"VisitorIdentity":{"type":"object","properties":{"externalId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"CreateRuntimeSessionRequest":{"type":"object","properties":{"slug":{"type":"string"},"apiKey":{"type":"string"},"visitor":{"$ref":"#/components/schemas/VisitorIdentity"},"contextToken":{"type":"string"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"RuntimeSession":{"type":"object","required":["sessionToken","expiresIn"],"properties":{"sessionToken":{"type":"string"},"expiresIn":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"}}},"RuntimeSessionEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/RuntimeSession"}}},"DevicePushPlatform":{"type":"string","enum":["android","ios","flutter","react_native","kotlin","swift","web"]},"DevicePushProvider":{"type":"string","enum":["fcm","apns","apns_voip"]},"DevicePushAudience":{"type":"string","enum":["visitor","customer","agent","admin"]},"SdkCallMode":{"type":"string","enum":["basic","native-phone"]},"RegisterDevicePushTokenRequest":{"type":"object","required":["platform","token"],"properties":{"platform":{"$ref":"#/components/schemas/DevicePushPlatform"},"provider":{"$ref":"#/components/schemas/DevicePushProvider","default":"fcm"},"token":{"type":"string","description":"FCM, APNs, or APNs VoIP token returned by the client app."},"deviceId":{"type":"string","description":"Stable app-generated device identifier. Do not send hardware identifiers."},"appId":{"type":"string","description":"Bundle ID, package name, or application ID."},"audience":{"$ref":"#/components/schemas/DevicePushAudience","default":"visitor"},"externalId":{"type":"string","description":"Customer-user or visitor ID from the customer's application."},"agentId":{"type":"string","description":"Optional Ringnity agent ID when the runtime belongs to an agent surface."},"callMode":{"$ref":"#/components/schemas/SdkCallMode","default":"basic"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"UnregisterDevicePushTokenRequest":{"type":"object","properties":{"deviceId":{"type":"string"},"provider":{"$ref":"#/components/schemas/DevicePushProvider","default":"fcm"},"token":{"type":"string"}},"anyOf":[{"required":["deviceId"]},{"required":["token"]}]},"DevicePushToken":{"type":"object","required":["id","clientId","platform","provider","audience","enabled"],"properties":{"id":{"type":"string"},"clientId":{"type":"string"},"platform":{"$ref":"#/components/schemas/DevicePushPlatform"},"provider":{"$ref":"#/components/schemas/DevicePushProvider"},"audience":{"$ref":"#/components/schemas/DevicePushAudience"},"deviceId":{"type":"string","nullable":true},"appId":{"type":"string","nullable":true},"externalId":{"type":"string","nullable":true},"agentId":{"type":"string","nullable":true},"callMode":{"$ref":"#/components/schemas/SdkCallMode"},"enabled":{"type":"boolean"},"lastSeenAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"DevicePushTokenEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["device"],"properties":{"device":{"$ref":"#/components/schemas/DevicePushToken"}}}}},"DevicePushTokenDisabledEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["disabled"],"properties":{"disabled":{"type":"integer","minimum":0}}}}},"DeveloperSettings":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/Tenant"},"allowedDomains":{"description":"Domain list is limited by the tenant plan contract quota `allowed_domains`.","type":"array","items":{"type":"string"}},"publicKey":{"type":"string"},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCapability"}}}},"DeveloperSettingsEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/DeveloperSettings"}}},"UpdateAllowedDomainsRequest":{"type":"object","required":["allowedDomains"],"properties":{"allowedDomains":{"type":"array","items":{"type":"string"}}}},"DeveloperTestRequest":{"type":"object","properties":{"origin":{"type":"string"},"slug":{"type":"string"},"service":{"$ref":"#/components/schemas/ServiceKey"}}},"ServerApiScope":{"type":"string","enum":["server:health","server:tenant:read","server:visitor-context:write","server:agent-token:write","server:admin-token:write","server:reports:read","server:webhook:read","server:webhook:write","server:contacts:read","server:contacts:write"]},"ServerApiCredential":{"type":"object","required":["id","name","scopes"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"environment":{"type":"string","enum":["test","live"]},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ServerApiScope"}},"isActive":{"type":"boolean"},"secretPreview":{"type":"string"},"lastUsedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ServerApiCredentialEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"credential":{"$ref":"#/components/schemas/ServerApiCredential"}}}}},"ServerApiCredentialListEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"credentials":{"type":"array","items":{"$ref":"#/components/schemas/ServerApiCredential"}}}}}},"ServerApiCredentialSecretEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"credential":{"$ref":"#/components/schemas/ServerApiCredential"},"secret":{"type":"string","description":"Returned once. Store only on customer backend servers."}}}}},"CreateServerApiCredentialRequest":{"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string"},"environment":{"type":"string","enum":["test","live"],"default":"live"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ServerApiScope"}}}},"UpdateServerApiCredentialRequest":{"type":"object","properties":{"name":{"type":"string"},"environment":{"type":"string","enum":["test","live"]},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ServerApiScope"}},"isActive":{"type":"boolean"}}},"CreateVisitorContextTokenRequest":{"type":"object","properties":{"visitor":{"$ref":"#/components/schemas/VisitorIdentity"},"metadata":{"$ref":"#/components/schemas/AnyObject"},"expiresIn":{"type":"integer","default":900}}},"CreateAgentTokenRequest":{"type":"object","properties":{"agentId":{"type":"string"},"username":{"type":"string"},"name":{"type":"string"},"departmentId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresIn":{"type":"integer","default":900}}},"CreateAdminTokenRequest":{"type":"object","properties":{"adminActorId":{"type":"string"},"username":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresIn":{"type":"integer","default":900}}},"SdkToken":{"type":"object","required":["token","expiresIn"],"properties":{"token":{"type":"string"},"tokenType":{"type":"string","default":"Bearer"},"expiresIn":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"scopes":{"type":"array","items":{"type":"string"}}}},"SdkTokenEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/SdkToken"}}},"ContactInput":{"type":"object","required":["name","phone"],"properties":{"externalId":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string","format":"email"},"company":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}},"ContactPatchInput":{"type":"object","properties":{"externalId":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string","format":"email"},"company":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}},"Contact":{"allOf":[{"$ref":"#/components/schemas/ContactInput"},{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"source":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}]},"ContactEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"}}}}},"ContactDeletedEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["deleted","id"],"properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string"}}}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"hasMore":{"type":"boolean"}}},"ContactListEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["contacts"],"properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}},"WebhookInput":{"type":"object","required":["url","events"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string"}}},"WebhookPatchRequest":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"secret":{"type":"string"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"secretPreview":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string"}}}}},"WebhookListEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"availableEvents":{"type":"array","items":{"type":"string"}}}}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"webhookId":{"type":"string"},"event":{"type":"string"},"deliveryId":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"},"responseStatus":{"type":"integer"},"responseBody":{"type":"string"},"errorMessage":{"type":"string"},"durationMs":{"type":"integer"},"attempt":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"}}},"WebhookDeliveryListEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}},"WebhookTestRequest":{"type":"object","properties":{"webhookId":{"type":"string"},"event":{"type":"string"}}},"WebhookTestEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnyObject"}}},"AgentProfile":{"type":"object","required":["agentId"],"properties":{"agentId":{"type":"string"},"username":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"departmentId":{"type":"string"},"departmentName":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}},"AgentProfileEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/AgentProfile"},"tenant":{"$ref":"#/components/schemas/Tenant"}}}}},"Presence":{"type":"object","properties":{"agentId":{"type":"string"},"status":{"type":"string","enum":["available","busy","offline"]},"online":{"type":"boolean"},"lastActivityAt":{"type":"string","format":"date-time"},"currentCallWith":{"type":"string"}}},"PresenceEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Presence"}}},"UpdatePresenceRequest":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["available","busy","offline","online","unavailable"]}}},"Conversation":{"type":"object","required":["conversationId","status"],"properties":{"conversationId":{"type":"string"},"conversationNumber":{"type":"string"},"ticketId":{"type":"string"},"contactId":{"type":"string"},"visitorId":{"type":"string"},"departmentId":{"type":"string"},"assignedAgentId":{"type":"string"},"channel":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"},"subject":{"type":"string"},"lastMessageAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ConversationEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"conversation":{"$ref":"#/components/schemas/Conversation"}}}}},"ConversationListEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["conversations"],"properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"nextCursor":{"type":"string"}}}}},"AssignConversationRequest":{"type":"object","properties":{"assignedAgentId":{"type":"string","nullable":true,"description":"Target agent ID. Omit to let the current agent accept the conversation."},"assignedDepartmentId":{"type":"string","nullable":true,"description":"Target department ID when transferring back to a team queue."},"reason":{"type":"string","maxLength":500},"isTransfer":{"type":"boolean","default":false}}},"Assignment":{"type":"object","properties":{"assignmentId":{"type":"string"},"conversationId":{"type":"string"},"clientId":{"type":"string"},"assignedAgentId":{"type":"string","nullable":true},"assignedDepartmentId":{"type":"string","nullable":true},"assignedByAgentId":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"AssignmentEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["assignment"],"properties":{"assignment":{"$ref":"#/components/schemas/Assignment"},"conversation":{"$ref":"#/components/schemas/Conversation"}}}}},"Message":{"type":"object","properties":{"messageId":{"type":"string"},"conversationId":{"type":"string"},"senderType":{"type":"string"},"senderAgentId":{"type":"string"},"senderContactId":{"type":"string"},"body":{"type":"string"},"messageType":{"type":"string"},"metadata":{"$ref":"#/components/schemas/AnyObject"},"clientMessageId":{"type":"string"},"sentAt":{"type":"string","format":"date-time"},"editedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time"}}},"MessageEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/Message"}}}}},"MessageListEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"nextCursor":{"type":"string"}}}}},"SendMessageRequest":{"type":"object","required":["body"],"properties":{"body":{"type":"string"},"messageType":{"type":"string","default":"text"},"metadata":{"$ref":"#/components/schemas/AnyObject"},"clientMessageId":{"type":"string"}}},"VisitorMessageRequest":{"allOf":[{"$ref":"#/components/schemas/SendMessageRequest"},{"type":"object","properties":{"visitor":{"$ref":"#/components/schemas/VisitorIdentity"}}}]},"MessagePatchRequest":{"type":"object","properties":{"body":{"type":"string"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"ReportPeriod":{"type":"object","required":["type","start","end"],"properties":{"type":{"type":"string","enum":["today","7days","30days","custom"]},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"ReportCallSummary":{"type":"object","properties":{"totalIncoming":{"type":"integer"},"totalAnswered":{"type":"integer"},"totalMissed":{"type":"integer"},"answerRate":{"type":"integer","minimum":0,"maximum":100},"avgDurationSeconds":{"type":"integer"},"totalHandled":{"type":"integer"},"currentQueueCount":{"type":"integer"}}},"ReportChatSummary":{"type":"object","properties":{"totalConversations":{"type":"integer"},"openConversations":{"type":"integer"},"pendingConversations":{"type":"integer"},"resolvedConversations":{"type":"integer"},"closedConversations":{"type":"integer"},"totalMessages":{"type":"integer"},"agentMessages":{"type":"integer"},"visitorMessages":{"type":"integer"},"conversationResolutionRate":{"type":"integer","minimum":0,"maximum":100}}},"ReportSatisfactionSummary":{"type":"object","properties":{"avgRatingScore":{"type":"number"},"totalRatings":{"type":"integer"},"satisfactionRate":{"type":"integer","minimum":0,"maximum":100}}},"ReportSummary":{"allOf":[{"$ref":"#/components/schemas/ReportCallSummary"},{"$ref":"#/components/schemas/ReportChatSummary"},{"$ref":"#/components/schemas/ReportSatisfactionSummary"},{"type":"object","properties":{"calls":{"$ref":"#/components/schemas/ReportCallSummary"},"chat":{"$ref":"#/components/schemas/ReportChatSummary"},"satisfaction":{"$ref":"#/components/schemas/ReportSatisfactionSummary"}}}]},"ReportAgentBreakdownItem":{"type":"object","properties":{"agentId":{"type":"string"},"agentName":{"type":"string"},"username":{"type":"string"},"callsHandled":{"type":"integer"},"avgDurationSeconds":{"type":"integer"},"avgRating":{"type":"number"},"totalRatings":{"type":"integer"},"conversationsAssigned":{"type":"integer"}}},"ReportTimeseriesPoint":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date"},"callsTotal":{"type":"integer"},"callsAnswered":{"type":"integer"},"callsMissed":{"type":"integer"},"conversations":{"type":"integer"},"conversationsResolved":{"type":"integer"},"messages":{"type":"integer"}}},"Report":{"type":"object","required":["period","summary","agentBreakdown","timeseries"],"properties":{"period":{"$ref":"#/components/schemas/ReportPeriod"},"summary":{"$ref":"#/components/schemas/ReportSummary"},"agentBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/ReportAgentBreakdownItem"}},"timeseries":{"type":"array","items":{"$ref":"#/components/schemas/ReportTimeseriesPoint"}}}},"ReportSummaryEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Report"}}},"ReportTimeseriesEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["period","timeseries"],"properties":{"period":{"$ref":"#/components/schemas/ReportPeriod"},"timeseries":{"type":"array","items":{"$ref":"#/components/schemas/ReportTimeseriesPoint"}}}}}},"ReportExportEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["report","exportedAt","format"],"properties":{"report":{"$ref":"#/components/schemas/Report"},"exportedAt":{"type":"string","format":"date-time"},"format":{"type":"string","enum":["json","csv"]}}}}},"AdminTenantEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/Tenant"},"admin":{"$ref":"#/components/schemas/AnyObject"}}}}},"DomainListEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"allowedDomains":{"type":"array","items":{"type":"string"}}}}}},"ServiceListEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"capabilities":{"$ref":"#/components/schemas/AnyObject"},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCapability"}}}}}},"SubscriptionEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/AnyObject"}}}}},"AiReadinessEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"ai":{"$ref":"#/components/schemas/AnyObject"},"canUseAiFeature":{"type":"boolean"}}}}},"StaffSummaryEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnyObject"}}},"Readiness":{"type":"object","properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCapability"}},"ai":{"$ref":"#/components/schemas/AnyObject"},"reports":{"$ref":"#/components/schemas/AnyObject"}}},"ReadinessEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Readiness"}}},"CallSessionType":{"type":"string","enum":["audio","video"]},"CallSessionDirection":{"type":"string","enum":["inbound","outbound"]},"CallSessionStatus":{"type":"string","enum":["started","answered","ended","missed","failed"]},"CallSession":{"type":"object","required":["id","conversationId","type","direction","status"],"properties":{"id":{"type":"string"},"conversationId":{"type":"string"},"type":{"$ref":"#/components/schemas/CallSessionType"},"direction":{"$ref":"#/components/schemas/CallSessionDirection"},"status":{"$ref":"#/components/schemas/CallSessionStatus"},"startedAt":{"type":"string","format":"date-time"},"answeredAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"},"durationSeconds":{"type":"integer","nullable":true},"endReason":{"type":"string","nullable":true},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"CreateCallSessionRequest":{"type":"object","required":["conversationId","type"],"properties":{"conversationId":{"type":"string"},"type":{"$ref":"#/components/schemas/CallSessionType"},"direction":{"$ref":"#/components/schemas/CallSessionDirection","default":"inbound"},"status":{"$ref":"#/components/schemas/CallSessionStatus","default":"started"},"sessionToken":{"type":"string","description":"Visitor chat session token when called from public visitor runtime."},"startedAt":{"type":"string","format":"date-time"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"EndCallSessionRequest":{"type":"object","properties":{"reason":{"type":"string","maxLength":255},"sessionToken":{"type":"string","description":"Visitor chat session token when called from public visitor runtime."}}},"CallSessionEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["callSession"],"properties":{"callSession":{"$ref":"#/components/schemas/CallSession"}}}}},"VisitorSessionRequest":{"type":"object","properties":{"visitor":{"$ref":"#/components/schemas/VisitorIdentity"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"VisitorSessionEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnyObject"}}},"VisitorConversationRequest":{"type":"object","properties":{"subject":{"type":"string"},"visitor":{"$ref":"#/components/schemas/VisitorIdentity"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"TicketEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnyObject"}}},"AvailabilityEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"available":{"type":"boolean"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"reason":{"type":"string"}}}}},"AttachmentRequest":{"type":"object","properties":{"filename":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"AttachmentEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnyObject"}}},"DeleteMediaRequest":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}},"AttachmentDeleteEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["message","deleted"],"properties":{"message":{"$ref":"#/components/schemas/Message"},"attachment":{"$ref":"#/components/schemas/AnyObject"},"deleted":{"type":"boolean","const":true}}}}},"CallLinkRequest":{"type":"object","properties":{"service":{"type":"string","enum":["voice_call","video_call"]},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"CallLinkEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnyObject"}}},"ReceiptEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnyObject"}}},"AiRoutingEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["human_only","ai_first","ai_assisted"]},"canUseAi":{"type":"boolean"},"humanFallbackAvailable":{"type":"boolean"}}}}},"AiConversationRequest":{"type":"object","properties":{"visitor":{"$ref":"#/components/schemas/VisitorIdentity"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"AiConversationEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"aiConversationId":{"type":"string"},"conversationId":{"type":"string"}}}}},"AiChatRequest":{"type":"object","required":["message"],"properties":{"aiConversationId":{"type":"string"},"conversationId":{"type":"string"},"message":{"type":"string"},"stream":{"type":"boolean","description":"When true, SDKs should use the realtime streaming contract for response deltas."},"metadata":{"$ref":"#/components/schemas/AnyObject"}}},"AiChatEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"aiConversationId":{"type":"string"},"conversationId":{"type":"string"},"message":{"type":"string"},"handoffRecommended":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/AnyObject"}}}}},"KnowledgeSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"limit":{"type":"integer","default":5}}},"KnowledgeSearchEnvelope":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AnyObject"}}}}}},"KnowledgeUrlRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"AiKnowledgeEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AnyObject"}},"additionalProperties":true}}}}