Xentree Docs
StatusMy Xentree
StatusMy Xentree
  1. Documentation
  • Documentation
    • Introduction
    • Quickstart
    • Authentication
    • Conversations
    • Knowledge Base
    • Organizations
    • Custom Domains
    • Admin Stats and Members
    • Profile & Analytics
    • Xentree English
    • Xentree Live
    • Skills Connector
    • Integration Tokens
    • Xentree Connect
    • API Keys
    • Webhooks
    • Subscriptions and Entitlements
    • Errors and Limits
  • API Reference
    • Authentication
      • Register a new user
      • Log in and get an access token
      • Refresh an access token
      • Log out the current user
      • Get the current authenticated user
      • Update the current authenticated user
    • Conversations
      • List available AI providers
      • Generate an AI response
      • List conversations for the current user
      • Create a conversation
      • Delete a conversation
      • Get messages for a conversation
      • Start a conversation session
      • Update session activity
      • End a conversation session
      • Get current session status
      • Search indexed user content
      • List notes
      • Create a note
      • Update a note
      • Delete a note
    • Knowledge Base
      • Search the knowledge base
      • List documents
      • Upload document
      • Query knowledge
    • Organizations
      • List organizations for the current user
      • Create an organization
      • Get organization details
      • Update organization details
      • Delete an organization
      • List organization members
      • Add a member to an organization
      • Update a member's role
      • Comprehensive member update (role, organization, team)
      • Remove a member from an organization
    • Custom Domains
      • Configure organization custom domain
      • Get organization custom-domain status
    • Admin Stats & Members
      • Engagement dashboard
      • Engagement member detail
      • Progress KPI cards
      • List learning objectives
      • Create learning objective
      • Archive learning objective
      • Suggest learning objectives (with draft)
      • Progress members table
      • Impact KPI cards
      • List learning targets
      • Create or update learning target
      • Suggest learning targets
      • Export admin stats report as PDF
      • Export admin stats report as XLSX
    • Profile & Analytics
      • Get my XP profile
      • Get a user's public profile
      • Get streak status
      • Get weekly XP activity
      • Get learning pulse (365-day heatmap)
      • Get daily quests
      • Get learning time analytics
    • Xentree English
      • List XEL modules with user progress
      • Get XEL module details
      • Start an XEL module
      • Complete an XEL module
      • Regenerate a task variant
      • Get current XPI breakdown
      • Get XPI history
      • Start a learning session
      • End a learning session
      • Save a transcript entry
      • Get transcripts for a session
      • Submit a learning task response
      • Run AI evaluation for speaking or writing
      • Get the XEL dashboard overview
    • Xentree Live
      • Get remaining Xentree Live quota
      • Start a live session
      • Update an active live session heartbeat
      • End a live session
      • Update the user nickname used in Xentree Live
      • List live transcripts for the current user
      • Save live session transcripts
      • Get a single live transcript
    • Skills Connector
      • List active integrations for the current user
      • Start the Google Calendar OAuth flow
    • Integration Tokens
      • Issue user- or organization-scoped RS256 integration grant token
      • Verify integration token signature and subject claims
      • Revoke integration token by token or jti
      • Rotate integration grant and optionally revoke previous token
      • Get active JWKS material for an integration subject
      • Get active integration key fingerprints for a subject
    • API Keys
      • List API keys
      • Create an API key
      • Delete an API key
    • Health
      • Health check
    • Xentree Connect
      • List Connect Clients
      • Create Connect Client
      • Get Connect Client
      • Update Connect Client
      • List Connected People
      • Toggle Connect Client Active
      • Get Consent Context
      • Deprovision Connect Member
      • Launch Connect
      • Revoke Own Connect Binding
      • Revoke Organization Connect Binding
      • Claim Connect Session
      • List My Connect Bindings
    • Organization Webhooks
      • Create Webhook
      • List Webhooks
      • Get Webhook
      • Update Webhook
      • Delete Webhook
      • List Deliveries
      • Get Delivery
      • Rotate Webhook Secret
      • Send Test Ping
    • Skill Vault
      • List Skills
      • Create Skill
      • Get Active Organization
      • Set Active Organization
      • Clear Active Organization
      • Create Skill Export
      • Download Skill Export
      • Get Skill Summary
      • Get Skill
      • Update Skill
      • Archive Skill
      • Download Skill Md
      • List Skill Grants
      • Grant Skill To Organization
      • Revoke Skill Organization Grant
    • Subscriptions
      • Get My Limits
      • Get My Subscription
      • Get My Usage
      • Cancel Subscription (Stop Renewing)
      • Cancel Queued Renewal (Stop Renewing)
    • Payments
      • Create Xendit Checkout (IDR)
      • Create PayPal Order (USD)
      • Confirm Xendit Payment
      • Capture PayPal Order
      • Get PayPal Client Token
      • Quote Extra Team Seats
      • Buy Extra Team Seats (Xendit)
      • Buy Extra Team Seats (PayPal)
    • Coupons
      • Validate Coupon
    • User Sessions
      • List My Signed-in Devices
      • Sign Out a Device
  • Schemas
    • Error
    • ConfigureCustomDomainRequest
    • SimpleDetailResponse
    • CustomDomainStatus
    • HealthLivenessResponse
    • TokenResponse
    • UserProfile
    • SimpleMessageResponse
    • LogoutResponse
    • ChatRequest
    • ChatResponse
    • ConversationCreateRequest
    • ConversationResponse
    • CoreSearchConversationResult
    • CoreSearchMessageResult
    • CoreSearchResponse
    • NoteCreate
    • NoteUpdate
    • NoteResponse
    • CoreConversationSessionStartResponse
    • CoreConversationSessionActivityResponse
    • CoreConversationSessionEndResponse
    • CoreConversationSessionStatusResponse
    • AdminStatsOrganizationSummary
    • AdminStatsDateRangeSummary
    • AdminStatsKPIStat
    • AdminStatsPulseDay
    • AdminStatsPulseSummary
    • AdminStatsTeamPulse
    • AdminStatsTrendPoint
    • AdminStatsDistributionBucket
    • AdminStatsCohortRetentionCell
    • AdminStatsCohortRetentionRow
    • AdminStatsDashboardResponse
    • AdminStatsCohortAnalyticsRow
    • AdminStatsUserDetailResponse
    • AdminStatsCohortRetentionAnalytics
    • AdminStatsCohortRetentionResponse
    • AdminStatsMemberActivityRow
    • AdminStatsAffiliation
    • AdminStatsMemberDirectoryRow
    • AdminStatsMutationResponse
    • ProgressKPIItem
    • ProgressObjectiveResponse
    • ProgressKPIResponse
    • ProgressKeyResultPayload
    • ProgressObjectiveCreateRequest
    • ProgressObjectiveSuggestRequest
    • ProgressObjectiveKeyResult
    • ProgressObjectiveSuggestedItem
    • ProgressMembersResponse
    • ProgressObjectiveSuggestResponse
    • ProgressTrendResponse
    • ProgressMemberAttempt
    • ProgressMemberSession
    • ProgressMemberRow
    • ProgressDistributionBucket
    • ProgressDistributionResponse
    • ImpactKPIItem
    • ImpactKPIResponse
    • ImpactTrendResponse
    • ImpactLevelItem
    • ImpactLevelProgressionResponse
    • LearningTargetResponse
    • ImpactTeamBreakdownItem
    • ImpactTeamBreakdownResponse
    • ImpactTopPerformerItem
    • ImpactTopPerformersResponse
    • LearningTargetCreateRequest
    • LearningTargetListResponse
    • KnowledgeSearchResponse
    • LearningTargetSuggestResponse
    • RagDocument
    • LVIWeightResponse
    • LVIWeightUpdateRequest
    • IntegrationOut
    • KnowledgeSearchRequest
    • KnowledgeSearchResultItem
    • RagUploadResponse
    • RagQueryRequest
    • RagQueryResponse
    • LiveStartSessionRequest
    • OrganizationResponse
    • LiveSessionResponse
    • LiveQuotaResponse
    • TranscriptTurn
    • XELTaskSubmissionRequest
    • SaveLiveTranscriptsRequest
    • OrganizationCreateRequest
    • MemberResponse
    • XELModuleSummary
    • XELModuleDetail
    • XELTaskSubmissionResponse
    • XELEvaluationResponse
    • XELDashboardResponse
    • XELModuleStartResponse
    • XELSessionStartRequest
    • XELModuleCompleteResponse
    • XELTaskRegenerateRequest
    • XELTaskRegenerateResponse
    • XELXpiResponse
    • XELXpiHistoryItem
    • XELSessionStartResponse
    • XELSessionEndRequest
    • XELSessionEndResponse
    • XELTranscriptSaveRequest
    • XELTranscriptSaveResponse
    • XELTranscriptItem
    • LiveSessionEndResponse
    • LiveSessionHeartbeatResponse
    • LiveNicknameResponse
    • LiveTranscriptSaveResponse
    • LiveTranscriptListItem
    • LiveTranscriptListResponse
    • LiveTranscriptDetailResponse
    • XPProfileResponse
    • PublicXPProfileResponse
    • StreakStatusResponse
    • WeeklyActivityResponse
    • LearningPulseDayEntry
    • APIKeyResponse
    • LearningPulseResponse
    • IntegrationGrantRequest
    • QuestItem
    • IntegrationGrantResponse
    • QuestsResponse
    • IntegrationVerifyRequest
    • LearningTimeAnalyticsResponse
    • IntegrationVerifyResponse
    • APIKeyCreateRequest
    • IntegrationRevokeRequest
    • IntegrationRevokeResponse
    • IntegrationJWKSResponse
    • IntegrationFingerprintResponse
    • ConnectClientResponse
    • ConnectClientCreateRequest
    • IntegrationRotateRequest
    • ConnectClientUpdateRequest
    • IntegrationRotateResponse
    • ConnectedPersonResponse
    • WebhookCreate
    • WebhookCreated
    • WebhookOut
    • WebhookUpdate
    • DeliveryPage
    • WebhookDeliveryOut
    • WebhookDeliveryDetail
    • TestPingAccepted
    • SkillMarkdownInput
    • ActiveOrganizationInput
    • GrantInput
    • ConsentContextRequest
    • Body_deprovision_connect_member_connect_v1_deprovision__client_id__post
    • Body_launch_connect_connect_v1_launch__client_id__post
    • SessionClaimRequest
    • ErrorResponse
    • RenewalWindowClosedError
    • NewOrganizationSpec
    • CheckoutRequest
    • XenditCheckoutResponse
    • PayPalOrderResponse
    • PaymentConfirmResponse
    • SeatRequest
    • SeatQuote
    • CouponValidationResponse
    • FlexibleEnterpriseDetail
    • SubscriptionMeResponse
    • CancelSubscriptionResponse
    • CancelQueuedResponse
    • UserSession
    • UserSessionList
    • ConsentContextResponse
    • DeprovisionResponse
    • MyConnectBinding
  1. Documentation

Custom Domains

Organization administrators can provision customer hostnames when Xentree has enabled their organization's custom-domain entitlement.

Set up in the dashboard#

Organization administrators can set up a custom domain without calling the API.
1.
Open the Admin Panel / Dashboard.
2.
Under Organization, click Set up custom domain.
3.
Enter the subdomain you want to use as your URL, for example learn.yourcompany.com, then click Provision.
4.
Add the two DNS records shown in the popup at your DNS provider: a CNAME record and a TXT record.
5.
Wait until Verification and SSL change from Pending to Active. This can take a few minutes after DNS propagates.
Your organization must have the custom-domain entitlement, and the subdomain must follow the rules in step 1 below. The next section describes the same flow through the API.

Step-by-step (API)#

Follow these steps to serve your organization on your own hostname, for example learn.yourcompany.com.

Before you start#

You are an administrator of the organization and have a Bearer token.
Your organization is entitled to custom domains. This is included with the Team plan for organizations with 1,000 licenses, or 100 licenses on an annual subscription. Without it, both endpoints return 403.
You can edit DNS records for the domain you want to use.

1. Choose a hostname#

Use a subdomain of a domain you control, such as learn.yourcompany.com. The following are rejected with 422:
A bare domain (yourcompany.com). A subdomain is required.
IP addresses and special-use names (.local, .internal, .test, .example, and similar). learn.customer.example in the examples below is a placeholder only.
xentree.ai and its subdomains.
Domains on shared hosting platforms (for example github.io, vercel.app, netlify.app, pages.dev).
URLs and ports are stripped, so https://Learn.YourCompany.com/ is stored as learn.yourcompany.com.

2. Configure the domain#

Keep these from the response:
cname_target: the DNS target for step 3.
cloudflare: provider-side details, used in step 4 if verification stays pending.
A new domain starts with verification_status and ssl_status at pending.
Calling the endpoint again with the same domain does not create a second hostname. It refreshes the status instead. An organization can hold only one custom hostname. To replace it, contact Xentree support.
Each administrator can configure a domain up to 10 times per hour. Beyond that the API returns 429 with a Retry-After header.

3. Add the DNS records#

At your DNS provider, create two records:
TypeNameValue
CNAMElearn (or the full hostname, depending on your provider)the cname_target value from step 2
TXTthe validation name provided by the providerthe validation value provided by the provider
The TXT record details are in the cloudflare object of the response (the dashboard shows the same records in its popup).

4. Check the status#

Each call refreshes pending status from the provider. Repeat it (for example every 30-60 seconds) until both fields are ready:
FieldValuesReady when
verification_statuspending, verified, failedverified
ssl_statuspending, active, failedactive
If either stays pending for long, check that both the CNAME and the TXT record are in place and have propagated. The cloudflare object in the response shows the records the provider expects.
If the provider is temporarily unreachable, this endpoint still returns 200 with the last stored state. Try again shortly.

5. Confirm and use the domain#

Your domain serves your organization only when verification_status is verified and ssl_status is active. Then open https://learn.yourcompany.com to confirm. GET /api/organizations/{org_id} returns the same values in its custom_domain_* fields.
The domain stops resolving if the organization becomes inactive or loses the custom-domain entitlement (for example, licenses drop below the threshold). It also stops if the provider later reports the hostname as blocked, failed or deleted.

Troubleshooting#

Response / symptomMeaning and what to do
403You are not an administrator of the organization, or the organization has no custom-domain entitlement.
404Organization not found.
409The domain is already assigned to another organization, or your organization already has a different custom hostname. Choose another hostname, or contact Xentree support to replace the existing one.
422The hostname is not allowed. See step 1.
429Too many configure attempts. Wait for the Retry-After period.
502The provider failed to create the hostname. Retry later. If it persists, contact Xentree support.
503The custom-domain service is not configured or unavailable. Contact Xentree support.
verification_status or ssl_status is failedCheck that the CNAME points exactly to cname_target and that no conflicting record exists for the same name. If it persists, contact Xentree support.
Stays pendingDNS may not have propagated yet, or the CNAME or TXT record is missing or wrong. See steps 3 and 4.

Configure domain#

POST /api/admin/organizations/{org_id}/custom-domain
{
  "domain": "learn.customer.example"
}
Xentree superadmins can optionally include existing_cloudflare_hostname_id to adopt a hostname that was already created in Cloudflare instead of creating a new one. Other callers receive 403. The Cloudflare hostname must match domain, otherwise the API returns 422.
Response contains cname_target, verification_status, ssl_status, and a cloudflare object with the provider-side hostname details. Point customer DNS CNAME at returned target, then poll status.
Domain conflict returns 409; provider failure returns 502; unavailable provider configuration returns 503.

Check status#

GET /api/admin/organizations/{org_id}/custom-domain/status returns current stored state and refreshes pending provider status when possible.

Status fields#

The same values are mirrored on the organization object (GET /api/organizations/{org_id}):
Organization fieldStatus response fieldDescription
custom_domaincustom_domainConfigured hostname
custom_domain_cname_targetcname_targetCNAME target for your DNS
custom_domain_verification_statusverification_statusHostname ownership verification state
custom_domain_ssl_statusssl_statusSSL certificate issuance state
cf_custom_hostname_idcf_custom_hostname_idCloudflare custom hostname ID
Both endpoints require Bearer auth, organization administrator role, and entitlement. Keep provider credentials server-side.
Modified at 2026-10-29 11:19:39
Previous
Organizations
Next
Admin Stats and Members
Built with