yanting/docs/API_CONTRACT_NOTES.md

App API Contract Notes

This is a handoff snapshot, not the product SSOT.

Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.

For full API/data details, read ../report-notebooklm-api/docs/API_AND_DATA.md from the monorepo root.

Configuration

The App reads the API base URL from:

RNB_API_BASE

If RNB_API_BASE is missing, live API requests throw an error. This is intentional to avoid silently pointing production builds at a debug backend.

Endpoints Currently Consumed

Method	Path	App use
GET	/feed/recommended	Recommended feed cards.
GET	/reports	Report list.
GET	/reports/{report_id}	Report detail skeleton and modules.
GET	/reports/{report_id}/modules/{module_id}	Module detail page content.
GET	/institutions	Institution list.
GET	/institutions/{institution_id}	Institution detail and recent reports.
GET	/listen	Listen list and mini-player entry.

Response Fields Currently Used

Report cards:

• report_id
• title_cn
• subtitle_cn
• one_liner
• institution
• topics
• released_at
• has_audio
• interpretation_label
• source_tier
• cache_version

Report detail:

• report_id
• title_cn
• subtitle_cn
• original_title
• one_liner
• institution
• source
• topics
• has_audio
• interpretation_label
• risk_disclaimer
• released_at
• cache_version
• modules

Display modules:

• module_id
• type
• layer
• render_mode
• has_detail_page
• is_publish_blocking
• requires_human_review
• sort_order
• title_cn
• content
• preview
• content_ref
• content_etag

Listen items:

• audio_id
• title_cn
• duration_sec
• report_id
• report_title_cn
• institution
• released_at
• cache_version

Institution:

• institution_id
• name_cn
• name_en
• institution_type
• source_tier
• website_url
• covered_topics
• report_count
• latest_report_at
• credibility_note
• intro_cn
• latest_report
• recent_reports

Module Rendering Behavior

• render_mode=inline: App renders content on the report detail page.
• render_mode=card_plus_page: App renders preview on the report detail page and opens module detail for full content.
• Unknown module type should not crash the App; it should fall back to a generic or hidden renderer.

Current renderer coverage includes:

• basic_info
• executive_overview
• core_insights
• key_data
• source_compliance
• audio
• institution
• timeline
• study_guide
• structure_graph
• related_sources
• differentiated_view
• weaknesses

Endpoints Not Yet Consumed

• GET /audio/{audio_id}/stream
• Auth endpoints.
• /me personal-state endpoints.
• POST /outbound/events

The UI currently uses placeholders for these blocked flows:

• Login prompt.
• Favorite action.
• Browse/history sync.
• Saved listen.
• Playback progress.
• Outbound confirmation.
• Real audio playback.

Public Field Boundary

The App must not rely on or display:

• display_version
• module version
• raw artifact payload
• raw NotebookLM IDs
• private object-storage references
• local paths
• auth internals

The App should use cache_version as the public cache/version signal.