Consumer-facing OSHUN BFF contract for the web shell.
Base Contract#
- Base URL:
http://localhost:4010in development orNEXT_PUBLIC_OSHUN_BFF_URL - Canonical paths are available both at root (
/home) and the compatibility/v1/*aliases (/v1/home) - Protected routes require
Authorization: Bearer <token> - Domain-scoped routes require at least one
domain:*ordomain:{domainId}scope - Aggregation routes return short-lived private cache headers and
x-oshun-cache: hit|miss
Shared Aggregation Semantics#
These routes share the same operational contract:
generatedAt: server timestamp for the envelopeauthorizedDomains: domains enabled by the caller's token scopespagination: cursor envelope withlimit,nextCursor,hasMore, andtotaldomainStatus: per-domainok | degraded | forbiddenerrors: normalized downstream call failures withdomain,stage, andmessage; entries are trimmed, empty messages fall back to a canonical adapter-failure message, duplicates collapse, and ordering is deterministicpartialFailure:truewhen any normalized downstream failure leaves the BFF returning a partial payloadtrace: request-scoped traceability envelope withcorrelationId,route,partialFailure,failureCount,degradedDomains, anddegradedStages
Shared response headers:
x-correlation-id: request correlation ID echoed by the BFFx-oshun-partial-response:true|falsex-oshun-partial-failure-count: normalized degraded-domain failure countx-oshun-degraded-domains: comma-separated degraded domains when presentx-oshun-degraded-stages: comma-separated degraded stages when present
Home#
GET /home#
Cross-domain home feed with three strips:
highlights: recommended or headline itemscontinue: resumable itemsfavorites: saved favorites summary strip
Query parameters:
highlightsLimit,highlightsCursorcontinueLimit,continueCursorfavoritesLimit,favoritesCursor
Key response fields:
userIdhighlights,continue,favoritespagination.highlights,pagination.continue,pagination.favorites
Each feed item includes:
iddomainkindtitlemeta
Continue / Resume#
GET /continue#
Unified resume feed across authorized domains.
Query parameters:
limitcursor
Key response fields:
userIditemspagination
Each item includes:
iddomainkindtitlemeta
Universal Search#
GET /search#
Cross-domain search across authorized shell domains.
Query parameters:
qorquerydomain=all|tara|veritas|nyx|arete|nisabalimitcursor
Key response fields:
userIdquerydomainFilterresultspagination
Each result includes:
iddomainkindtitlesummaryscore
GET /search/suggestions#
Search suggestions and recent-search support for the same domain surface.
Query parameters:
qorquerydomain=all|tara|veritas|nyx|arete|nisabalimitcursor
Key response fields:
userIdquerydomainFilterrecentsuggestionspagination
Each suggestion includes:
querysourceasrecent | trending | derivedscore
Library#
GET /library#
Unified saved-content and favorites feed.
Query parameters:
domain=all|tara|veritas|nyx|aretelimitcursor
Key response fields:
userIddomainFilteritemspagination
Each library item includes:
keyitemIddomainkinditemTypetitlesummarysavedAtdomainMeta
Current sources:
- Tara favorites
- Veritas saved articles
- Nyx saved sky objects
Activity#
GET /activity#
Unified activity timeline assembled from continue state first, with highlight/recommended fallback when a domain has no resumable item.
Query parameters:
limitcursor
Key response fields:
userIdtimelinepagination
Each timeline entry includes:
iddomainkindtitledetailoccurredAt
Notifications#
GET /notifications#
Unified notifications feed derived from aggregation signals plus user read and preference state.
Query parameters:
inbox=all|unread|prioritydomain=all|tara|veritas|nyx|arete|nisabalimitcursor
Key response fields:
userIdinboxFilterdomainFiltercounts.totalcounts.unreadcounts.prioritycounts.visiblenotificationspagination
Each notification includes:
iddomainkindprioritytitlebodytimestampread
Behavior notes:
- semantic cross-domain duplicates are deduplicated
- read-state writes and notification preference writes invalidate cached feeds
GET /notifications/preferences#
Reads per-domain notification preferences.
Key response fields:
userIdrevisionauthorizedDomainsscopeAuthorizedpreferences
PATCH /notifications/preferences/domains/:domainId#
Updates one domain's notification preference state for
tara|veritas|nyx|arete|nisaba|metis.
Allowed patch fields:
enabledpriorityOnlykinds.reminderkinds.updatekinds.eventkinds.insight
Profile#
GET /profile#
Returns the authenticated shell profile envelope.
Key response fields:
generatedAtrevisionidemaildisplayNameinitialsplanverifiedstatsdomainConnections
stats currently includes:
streakDayssavedItemsactiveDomains
Each domainConnections item includes:
idlabelaccentstatus
PATCH /profile#
Updates profile fields.
Allowed patch fields:
displayNameemail
Invalid or empty payloads return 400 with reason=invalid_profile_payload.
Preferences#
GET /preferences#
Returns the authenticated shell preference envelope.
Key response fields:
generatedAtuserIdrevisionpreferences.themepreferences.languagepreferences.accessibility.timezonepreferences.accessibility.calendarpreferences.notifications.pushEnabledpreferences.notifications.emailDigestEnabledpreferences.notifications.quietHoursEnabled
PATCH /preferences#
Updates shell preferences.
Allowed patch fields:
themeassystem | light | darklanguageasen | es | fr | de | ja | ar | zh | pt | ko | hiaccessibility.timezoneas an IANA timezone idaccessibility.calendarasgregory | buddhist | chinese | hebrew | indian | islamic | japanese | persiannotifications.pushEnablednotifications.emailDigestEnablednotifications.quietHoursEnabled
Invalid or empty payloads return 400 with
reason=invalid_preferences_payload.
Recommendations#
GET /recommendations#
Returns the cross-domain recommendation feed used by consumer shells.
Query parameters:
limitcursor
Key response fields:
generatedAtuserIditemspaginationdomainBreakdownerrorspartialFailure
Each recommendation includes:
iddomainitemTypetitlesubtitleexplanationreasonscoremeta
POST /v1/recommendations/feedback#
Records user feedback for a recommendation.
Required body fields:
itemIddomainsignal=hide|less|more
Optional body fields:
itemTypereason
Favorites#
GET /favorites#
Returns Tara favorites for the authenticated user.
Query parameters:
limitcursor
Key response fields:
generatedAtuserIditemspagination
Each item currently includes:
meditationIdtitledurationMinutescategoryfavoritedAt
POST /favorites/:meditationId#
Adds a Tara favorite and returns a toggle receipt with:
result.meditationIdresult.favoritedresult.favoritedAt
DELETE /favorites/:meditationId#
Removes a Tara favorite and returns the same toggle receipt shape.
Assistant#
POST /v1/assistant/sessions#
Creates a shell assistant session.
Optional body fields:
inputMode=text|voicelocaletimezonedeviceType=mobile|tablet|webappVersion
Response fields:
sessionIdcreatedAtauthorizedDomains
POST /v1/assistant/sessions/:sessionId/message#
Processes one assistant turn.
Required body fields:
text
Optional body fields:
inputMode=text|voicevoiceTranscriptConfidencelocale
Response fields:
sessionIdturnCountresponse.textresponse.ssmlresponse.cardsresponse.suggestedActionsresponse.navigateToresponse.shouldSpeakresponse.confidence
GET /v1/assistant/sessions#
Lists session summaries with:
sessionIdcreatedAtlastActivityAtturnCount
DELETE /v1/assistant/sessions/:sessionId#
Ends an assistant session and returns 204.
Routines#
GET /v1/routines/templates#
Returns routine templates for morning|evening|custom, optionally filtered by
type.
GET /v1/routines/recommendations#
Returns personalized routine recommendations.
Optional query parameters:
availableMinutespreferQuicklimit
Response fields:
timeOfDayrecommendations
GET /v1/routines#
Lists user routines.
POST /v1/routines#
Creates a routine from either:
templateId
Or:
nametypesteps
Optional creation fields include description, frequency, customDays,
scheduledTime, and notificationsEnabled.
PUT /v1/routines/:routineId#
Updates editable routine fields such as name, description, scheduledTime,
frequency, customDays, enabled, and notificationsEnabled.
DELETE /v1/routines/:routineId#
Deletes a routine and returns 204.
Routine Execution Lifecycle#
POST /v1/routines/:routineId/startPOST /v1/routines/executions/:execId/advancePOST /v1/routines/executions/:execId/pausePOST /v1/routines/executions/:execId/resumePOST /v1/routines/executions/:execId/abandonGET /v1/routines/executions/activeGET /v1/routines/historyGET /v1/routines/summary
Execution responses return the execution envelope, while history and summary
return executions and summary respectively.
Session Audio#
GET /sessions/:sessionId/audio#
Returns Tara session audio metadata and stream variants.
Optional query parameters:
quality=low|standard|high|lossless
Key response fields:
sessionIdtitleartistalbumartworkUrldurationSecondstracks.primarytracks.variantstracks.previewmarkersresumePositionSeconds
Device Tokens#
GET /v1/device-tokens#
Lists registered device tokens with:
platformtokenTypedeviceIdappVersionregisteredAtlastActiveAt
POST /v1/device-tokens#
Registers a push token.
Required body fields:
token
Optional body fields:
platform=ios|android|webtokenType=expo|fcm|apns|web-pushdeviceIdappVersion
DELETE /v1/device-tokens#
Unregisters a push token.
Required body fields:
token
Nisaba#
All Nisaba consumer routes require domain:* or domain:nisaba.
GET /nisaba/passages/daily#
Returns the authenticated user's daily Nisaba passage envelope.
Key response fields:
generatedAtuserIdrevisionpassagecompareTargetsnotebooksgroundedEvidenceViews
passage includes:
passageIdreferencetitleexcerptbodytraditionlanguagesourceNamecompareTargetCountannotationCountsavedhasHighlightsprogressPercentlastReadAtdailyreadingStatsrelatedConceptslaunch.targetPathlaunch.shellPath
compareTargets launch directly into Nisaba compare flows for the current
passage and selected target passage.
GET /nisaba/passages/:passageId#
Returns the same passage envelope for an explicit passage id.
GET /nisaba/passages/:passageId/annotations#
Lists revisioned annotations for a passage.
Query parameters:
visibility=all|private|sharedstatus=all|active|archivednotebookIdlimitcursor
Key response fields:
generatedAtuserIdrevisionpassageIdfiltersannotationspagination
Each annotation includes:
annotationIdpassageIdauthor.userIdauthor.displayNameselection.excerptselection.startOffsetselection.endOffsetnotecolorvisibilitystatustagsnotebookIdsevidenceViewIdscreatedAtupdatedAt
Unknown passage ids return 404. Unknown notebook or evidence references in
annotation writes also return 404.
POST /nisaba/passages/:passageId/annotations#
Creates an annotation.
Required body fields:
selection.excerptselection.startOffsetselection.endOffsetnotecolor=amber|azure|violet|sagevisibility=private|shared
Optional body fields:
tagsnotebookIdsevidenceViewIds
PATCH /nisaba/passages/:passageId/annotations/:annotationId#
Updates any subset of:
notecolorvisibilitystatus=active|archivedtagsnotebookIdsevidenceViewIds
GET /nisaba/passages/:passageId/compare#
Returns the Nisaba compare workspace envelope.
Query parameters:
targetPassageId
Key response fields:
generatedAtuserIdrevisioncompareIdsummarynotespassagetargetPassageavailableTargetsalignmentsnotebookslaunch
Each alignment includes:
alignmentIdlensleftExcerptrightExcerptsummaryannotationIdsevidenceViewIds
GET /nisaba/notebooks#
Lists Nisaba notebooks.
Query parameters:
status=all|active|archivedlimitcursor
Key response fields:
generatedAtuserIdrevisionstatusFilternotebookspagination
Each notebook summary includes:
notebookIdtitlesummarytagsstatuslinkedPassageIditemCountpassageCountannotationCountevidenceViewCountcompareItemCountupdatedAtlaunch
POST /nisaba/notebooks#
Creates a notebook.
Required body fields:
titlesummary
Optional body fields:
tagslinkedPassageId
If linkedPassageId is supplied, it must resolve to an existing passage.
GET /nisaba/notebooks/:notebookId#
Returns the notebook detail envelope. notebook.items contains notebook item
launch metadata for passage, annotation, grounded-evidence-view, and
compare resources.
PATCH /nisaba/notebooks/:notebookId#
Updates any subset of:
titlesummarytagsstatus=active|archived
POST /nisaba/notebooks/:notebookId/items#
Adds an item to a notebook.
Required body fields:
kind=passage|annotation|grounded-evidence-view|comparerefId
GET /nisaba/passages/:passageId/grounded-evidence#
Returns the grounded evidence view envelope for Nisaba reading and compare flows.
Query parameters:
view=reader|compare|source_lineagetargetPassageId
Key response fields:
generatedAtuserIdrevisionviewIdviewKindtitlequerygroundingStatusconfidenceanswerwarningssubjectcitationssourcesclaimChecksnotebookslaunchevidencePack
evidencePack includes:
evidencePackIdtitlesummarygroundingStatuscitationsevidencesourcesclaimChecksnotebookssourceGraphtagsgeneratedAtprocessingTimeMs
Errors#
Common auth and validation failures:
401withreason=missing_auth_contextwhen the token is absent or invalid403withreason=domain_scope_missingwhen the caller lacks required domain scope400with route-specific reasons for invalid cursors, limits, filters, or patch payloads
Source of Truth#
- OpenAPI:
apps/oshun/bff/openapi/oshun-bff.openapi.yaml - Contract tests:
apps/oshun/bff/src/__tests__/contract/shell-bff-contract.test.ts