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

Errors and Limits

This page describes the most common API error patterns across Xentree.

Standard status codes#

200 OK#

The request completed successfully.

201 Created#

A new resource was created successfully.

204 No Content#

The request succeeded and there is no response body.

400 Bad Request#

The request body or parameters were invalid.

401 Unauthorized#

Authentication is missing or invalid.

403 Forbidden#

The user is authenticated but does not have permission.
For API key requests, 403 can also indicate insufficient scope.

404 Not Found#

The resource does not exist or is not visible to the requester.

409 Conflict#

The request conflicts with current state, for example a duplicate webhook URL or exceeding the webhook limit.

428 Precondition Required#

An AI feature was called without a connected Google Gemini API key. Xentree AI features run on the user's own key (BYOK) and there is no platform fallback. Connect a key, then retry.
{
  "detail": "Google Gemini API Key is required to use this AI feature."
}
In streaming responses the same condition arrives as an event with status_code: 428 and code: "AI_KEY_REQUIRED". An invalid key is reported as 400 with code AI_KEY_INVALID.

429 Too Many Requests#

Returned when a limit, throttle, or quota condition is reached.

500 Internal Server Error#

An unexpected platform error occurred.

Xentree Live quota errors#

Live endpoints can return a quota-related error when a user exceeds the monthly allowance defined by the user’s plan.
Example:
{
  "detail": {
    "error": "live_quota_exceeded",
    "message": "Monthly Live session quota exceeded"
  }
}

Plan and entitlement errors#

Plan-gated features return 403 with upgrade_required: true:
{
  "detail": {
    "error": "feature_not_in_plan",
    "message": "Organization webhooks require an active Team or Enterprise plan.",
    "upgrade_required": true,
    "feature": "organization_webhooks"
  }
}
Monthly quotas (certificates, PDF uploads, quiz generations, YouTube minutes) return 429 with quota, plan, limit, and used fields. Use GET /api/subscriptions/limits and /usage to check them in advance. See Subscriptions and Entitlements.

Webhook limits#

LimitValue
Webhooks per organization20 (a further create returns 409)
Event payload size256 KB
Endpoint response time10 seconds (5 seconds to connect)
Delivery attempts12 per event
Signature timestamp tolerance300 seconds
See Webhooks for retry behavior and the circuit breaker.

API key scope errors#

Example insufficient scope payload:
{
  "detail": {
    "error": "INSUFFICIENT_API_KEY_SCOPE",
    "message": "API key lacks required scope for this endpoint",
    "required_scope": "organizations:write",
    "granted_scopes": ["organizations:read"]
  }
}

Best practices#

validate request payloads before sending them
retry only on safe, transient failures
handle 401 by refreshing or re-authenticating
handle 403 by checking organization role and API key scopes
handle 428 by prompting the user to connect their Gemini key
handle 429 with graceful backoff
always log response IDs and error payloads in client applications
Modified at 2026-10-24 07:48:19
Previous
Subscriptions and Entitlements
Next
Register a new user
Built with