API surface — generated¶

Generated by scripts/api_surface.py from the routers. Do not hand-edit; re-run the generator after any route change (python scripts/api_surface.py). This file is the docs<->code truth for the HTTP surface; CLAUDE.md keeps the curated, explained subset.

Total: 291 HTTP routes across 5 surfaces.

Overlay API (read-only) — 18 routes (prefix /api/overlay)
Corpus API — 62 routes (prefix /api/corpus)
Write-key API (capability mint + scoped compose) — 2 routes (prefix /api/writekey)
Observe API — 5 routes (prefix /api/observe)
Server (api_server.py) — 204 routes

Overlay API (read-only) — 18 routes¶

Method	Path	Handler
`GET`	`/api/overlay/audit/{session_id}`	`get_audit_report`
`GET`	`/api/overlay/capacitance/{session_id}`	`get_capacitance`
`GET`	`/api/overlay/composition/{session_id}`	`get_composition`
`GET`	`/api/overlay/cross-block-lens`	`get_cross_block_lens`
`GET`	`/api/overlay/diagonal/{session_id}/{dimension}`	`get_diagonal`
`GET`	`/api/overlay/eventuality/{session_id}`	`get_eventuality`
`GET`	`/api/overlay/mp/{session_id}`	`get_mp`
`GET`	`/api/overlay/omega/{session_id}`	`get_temporal_covariance_omega`
`GET`	`/api/overlay/pressure/{session_id}`	`get_pressure`
`GET`	`/api/overlay/recognition/compare`	`get_recognition_compare`
`GET`	`/api/overlay/recognition/{session_id}`	`get_recognition_report`
`GET`	`/api/overlay/recognition/{session_id}/articulate`	`articulate_recognition_report`
`GET`	`/api/overlay/story/compare`	`get_story_compare`
`GET`	`/api/overlay/story/{session_id}`	`get_story_contract`
`GET`	`/api/overlay/story/{session_id}/articulate`	`articulate_story_contract`
`GET`	`/api/overlay/surface/{session_id}`	`get_surface`
`GET`	`/api/overlay/surplus/{session_id}`	`get_surplus`
`GET`	`/api/overlay/viscosity/{session_id}`	`get_viscosity`

Corpus API — 62 routes¶

Method	Path	Handler
`POST`	`/api/corpus/associate`	`associate_manifolds`
`GET`	`/api/corpus/associations`	`list_associations`
`POST`	`/api/corpus/beings/define`	`define_beings`
`GET`	`/api/corpus/beings/{session_id}`	`list_beings`
`POST`	`/api/corpus/compare-sessions`	`compare_sessions`
`POST`	`/api/corpus/compose`	`compose`
`POST`	`/api/corpus/couple`	`couple_entities`
`POST`	`/api/corpus/cross-reader`	`cross_reader_comparison`
`POST`	`/api/corpus/dialogic`	`corpus_dialogic`
`GET`	`/api/corpus/dimensions/semantics`	`get_dimension_semantics`
`GET`	`/api/corpus/documents/{session_id}`	`list_session_documents`
`GET`	`/api/corpus/gem/compare/{gem_id_a}/{gem_id_b}`	`compare_gems`
`POST`	`/api/corpus/gem/crystallize`	`crystallize_gem`
`GET`	`/api/corpus/gem/histogram/{gem_id_a}/{gem_id_b}`	`gem_histogram`
`POST`	`/api/corpus/gem/instantiate`	`instantiate_gem_endpoint`
`GET`	`/api/corpus/gem/{gem_id}`	`get_gem`
`POST`	`/api/corpus/gem/{gem_id}/generate-report`	`generate_report`
`GET`	`/api/corpus/gem/{gem_id}/lens`	`gem_lens`
`PATCH`	`/api/corpus/gem/{gem_id}/metadata`	`patch_gem_metadata`
`GET`	`/api/corpus/gem/{gem_id}/reader-condition`	`get_reader_condition`
`GET`	`/api/corpus/gem/{gem_id}/three-layer`	`get_three_layer_state`
`GET`	`/api/corpus/gem/{gem_id}/worldlines`	`get_gem_worldlines`
`GET`	`/api/corpus/gems/corpus/{corpus_id}`	`list_corpus_gems`
`GET`	`/api/corpus/gems/session/{session_id}`	`list_session_gems`
`GET`	`/api/corpus/gems/{user_did}`	`list_user_gems`
`POST`	`/api/corpus/ingest`	`ingest_document`
`POST`	`/api/corpus/interstitial`	`corpus_interstitial`
`POST`	`/api/corpus/materiality`	`corpus_materiality`
`GET`	`/api/corpus/me`	`get_current_user`
`GET`	`/api/corpus/pathways`	`get_pathways`
`POST`	`/api/corpus/preset/load`	`load_preset_corpus`
`GET`	`/api/corpus/presets`	`get_presets`
`GET`	`/api/corpus/public/session/{session_id}`	`get_public_session`
`GET`	`/api/corpus/published`	`list_published_sessions`
`POST`	`/api/corpus/query`	`query_corpus`
`POST`	`/api/corpus/room-condition`	`get_room_condition`
`POST`	`/api/corpus/self-read`	`self_read`
`POST`	`/api/corpus/session/{session_id}/comment`	`post_comment`
`GET`	`/api/corpus/session/{session_id}/comments`	`get_comments`
`GET`	`/api/corpus/session/{session_id}/crystallization-surface`	`get_crystallization_surface`
`POST`	`/api/corpus/session/{session_id}/dimension-narrative/{dimension}`	`dimension_narrative`
`GET`	`/api/corpus/session/{session_id}/field-dynamics`	`get_session_field_dynamics`
`POST`	`/api/corpus/session/{session_id}/generate-report`	`generate_session_report`
`GET`	`/api/corpus/session/{session_id}/grammar`	`get_grammar_analysis`
`GET`	`/api/corpus/session/{session_id}/maturation-dynamics`	`get_session_maturation_dynamics`
`GET`	`/api/corpus/session/{session_id}/nearby`	`get_nearby_readers`
`GET`	`/api/corpus/session/{session_id}/open-secret`	`get_session_open_secret`
`GET`	`/api/corpus/session/{session_id}/overlay-surface`	`get_overlay_surface`
`GET`	`/api/corpus/session/{session_id}/perspectives`	`session_perspectives`
`POST`	`/api/corpus/session/{session_id}/publish`	`publish_session`
`GET`	`/api/corpus/session/{session_id}/reader-condition`	`get_session_reader_condition`
`GET`	`/api/corpus/session/{session_id}/ridge-monitor`	`get_ridge_monitor`
`GET`	`/api/corpus/session/{session_id}/spectral-trace`	`get_spectral_trace`
`GET`	`/api/corpus/session/{session_id}/spectral-trace`	`get_spectral_trace`
`GET`	`/api/corpus/session/{session_id}/surplus-profile`	`get_surplus_profile`
`GET`	`/api/corpus/session/{session_id}/teach/trajectory`	`teach_trajectory`
`GET`	`/api/corpus/sessions/{user_did}`	`list_user_sessions`
`POST`	`/api/corpus/sji/setup-drive`	`sji_setup_drive`
`POST`	`/api/corpus/sji/upload-doc`	`sji_upload_doc`
`GET`	`/api/corpus/state/{session_id}`	`get_manifold_state`
`GET`	`/api/corpus/surplus/{session_a}/{session_b}`	`cross_manifold_surplus`
`GET`	`/api/corpus/templates`	`list_templates`

Write-key API (capability mint + scoped compose) — 2 routes¶

Method	Path	Handler
`POST`	`/api/writekey/compose`	`compose`
`POST`	`/api/writekey/mint`	`mint`

Observe API — 5 routes¶

Method	Path	Handler
`GET`	`/api/observe/corpus-text`	`get_corpus_text`
`POST`	`/api/observe/drop`	`drop_text`
`GET`	`/api/observe/page`	`observe_page`
`POST`	`/api/observe/start`	`start_session`
`GET`	`/api/observe/state`	`get_state`

Server (api_server.py) — 204 routes¶

Method	Path	Handler
`GET`	`/`	`root`
`GET`	`/activities/recent`	`get_recent_activities`
`GET`	`/activity/{activity_id}/discoveries`	`get_activity_discoveries`
`GET`	`/activity/{activity_id}/status`	`get_activity_status`
`GET`	`/agent/coupling/{coupling_id}/state`	`get_agent_coupling_state`
`GET`	`/agent/couplings`	`list_agent_couplings`
`GET`	`/agent/state/{user_did}`	`get_agent_state`
`POST`	`/api/admin/reset-sessions`	`reset_sessions`
`POST`	`/api/checkpoint/all`	`checkpoint_all_users`
`POST`	`/api/checkpoint/{user_did}`	`checkpoint_user_state`
`POST`	`/api/clips`	`create_clip`
`POST`	`/api/clips/aggregate`	`aggregate_clips`
`GET`	`/api/clips/document/{document_id}`	`get_document_clips`
`GET`	`/api/clips/user/{user_did}`	`get_user_clips`
`GET`	`/api/clips/view/{aggregation_id}`	`view_aggregation`
`GET`	`/api/clips/{clip_id}`	`get_clip`
`GET`	`/api/clips/{clip_id}/compositional_neighbors`	`get_compositional_neighbors`
`POST`	`/api/comic/panel`	`annotate_comic_panel`
`GET`	`/api/content/{content_id}/accessibility`	`get_content_accessibility`
`GET`	`/api/corpus/{corpus_id}/query`	`query_corpus_endpoint`
`POST`	`/api/curate`	`curate_content`
`GET`	`/api/curation/{curation_id}/status`	`get_curation_status`
`GET`	`/api/debug/clips`	`debug_clips`
`GET`	`/api/debug/document-manifolds`	`debug_document_manifolds`
`GET`	`/api/debug/user-subfield-state`	`debug_user_subfield_state`
`GET`	`/api/demo/checkpoints`	`list_demo_checkpoints`
`POST`	`/api/demo/clear`	`clear_demo_state`
`POST`	`/api/demo/load/{checkpoint_name}`	`load_demo_checkpoint`
`POST`	`/api/demo/save/{checkpoint_name}`	`save_demo_checkpoint`
`GET`	`/api/diagonal_lens/{entity_a}/{entity_b}`	`compute_diagonal_lens`
`POST`	`/api/document/image`	`register_image_document`
`GET`	`/api/drive/documents`	`drive_documents`
`GET`	`/api/drive/folders`	`drive_folders`
`POST`	`/api/drive/import`	`drive_import`
`POST`	`/api/engage`	`engage_with_document`
`POST`	`/api/export_foam`	`export_foam`
`GET`	`/api/field/current-path`	`get_current_path`
`GET`	`/api/field/orientation-trajectory`	`get_orientation_trajectory`
`POST`	`/api/field/publish-public-sigma`	`publish_public_sigma`
`GET`	`/api/field/reachable-people`	`get_reachable_people`
`DELETE`	`/api/field/revoke-public-sigma`	`revoke_public_sigma`
`GET`	`/api/field/stability-topology`	`get_stability_topology`
`GET`	`/api/field/stability-topology/all`	`get_all_stability_topology`
`GET`	`/api/foam/coupling_observation/{user_a}/{user_b}`	`get_coupling_observation`
`GET`	`/api/foam/cross_aperture`	`get_cross_aperture_resonance`
`GET`	`/api/foam/observed/{user_name}`	`get_observed_state`
`POST`	`/api/foam/recompute_sigma`	`recompute_sigma_endpoint`
`GET`	`/api/foam/semantic_posture/{user_name}`	`get_semantic_posture`
`GET`	`/api/gems`	`list_gems`
`POST`	`/api/gems/crystallize`	`crystallize_gem`
`POST`	`/api/gems/{gem_id}/publish`	`publish_gem`
`POST`	`/api/gems/{gem_id}/view`	`view_gem_from_perspective`
`GET`	`/api/gems/{gem_id}/worldline`	`get_gem_worldline`
`GET`	`/api/github/content/{owner}/{repo}/{path:path}`	`github_content`
`GET`	`/api/github/files/{owner}/{repo}`	`github_files`
`POST`	`/api/github/import`	`github_import`
`GET`	`/api/github/repos`	`github_repos`
`GET`	`/api/github/tree/{owner}/{repo}`	`github_tree`
`POST`	`/api/image/annotate`	`annotate_image`
`POST`	`/api/image/annotate-url`	`annotate_image_from_url`
`GET`	`/api/llm-compositions`	`get_llm_compositions`
`GET`	`/api/llm-compositions/{composition_id}`	`get_composition`
`POST`	`/api/llm-compositions/{composition_id}/act`	`act_on_composition`
`GET`	`/api/mvco/buoys`	`list_mvco_buoys`
`GET`	`/api/mvco/diagonal/{station_id}`	`compute_sensor_diagonal_lensing`
`GET`	`/api/mvco/readings/{station_id}`	`get_mvco_readings`
`GET`	`/api/mvco/readings/{station_id}/framework/{framework}`	`get_mvco_readings_by_framework`
`POST`	`/api/protocol/coupling_preview`	`coupling_preview`
`GET`	`/api/protocol/curiosity_traces/{user_did}`	`get_curiosity_traces`
`POST`	`/api/protocol/fidelity_reconciliation`	`fidelity_reconciliation`
`GET`	`/api/read/document/{document_id}`	`get_read_document_content`
`PUT`	`/api/read/document/{document_id}`	`update_read_document`
`GET`	`/api/read/documents`	`get_read_documents`
`GET`	`/api/read/images`	`list_read_images`
`POST`	`/api/read/images`	`upload_read_image`
`POST`	`/api/rosetta/act`	`rosetta_act`
`POST`	`/api/rosetta/act_on_proposal`	`act_on_proposal`
`GET`	`/api/rosetta/differential/{user_id}`	`get_rosetta_differential`
`GET`	`/api/rosetta/document/{document_id}`	`get_rosetta_document`
`GET`	`/api/rosetta/documents`	`get_rosetta_documents`
`GET`	`/api/rosetta/lenses`	`get_available_lenses`
`GET`	`/api/rosetta/proposals/{user_id}`	`get_rosetta_proposals`
`GET`	`/api/sessions`	`list_sessions`
`POST`	`/api/sessions/backfill-corpus`	`backfill_corpus`
`GET`	`/api/sessions/grid`	`session_grid`
`GET`	`/api/sessions/ingested`	`get_ingested_ids`
`GET`	`/api/sessions/{session_id}`	`get_session_detail`
`GET`	`/api/sessions/{session_id}/text`	`get_session_text`
`DELETE`	`/api/social/delete/{activity_id}`	`delete_social_comment`
`POST`	`/api/social/like`	`observe_social_like`
`POST`	`/api/social/reply`	`observe_social_reply`
`POST`	`/api/social/repost`	`observe_social_repost`
`GET`	`/api/social/thread/{activity_id}`	`get_social_thread`
`GET`	`/api/sovereign/geometric_marginalia/{user_did}/{doc_id}`	`get_geometric_marginalia`
`GET`	`/api/sovereign/org_sigma/{org_id}`	`get_org_sigma`
`POST`	`/api/sovereign/vocabulary_recursion`	`vocabulary_recursion_endpoint`
`GET`	`/api/stream/info`	`get_activity_stream_info`
`POST`	`/api/stream/sidebar`	`get_stream_sidebar`
`POST`	`/api/stream/trace_neighbors`	`get_stream_trace_neighbors`
`POST`	`/api/vision/observe`	`observe_image_with_geodesics`
`POST`	`/auth/anon`	`create_anonymous_session`
`POST`	`/auth/login`	`login`
`POST`	`/auth/refresh`	`refresh_token`
`GET`	`/auth/session`	`get_session`
`POST`	`/comment`	`create_comment`
`POST`	`/community/{community_id}/generate-synthetic`	`generate_synthetic_community_topology`
`GET`	`/community/{community_id}/health`	`get_community_health`
`POST`	`/community/{community_id}/initialize`	`initialize_community_topology`
`GET`	`/community/{community_id}/members/{member_id}/signature`	`get_member_signature`
`GET`	`/community/{community_id}/power-centers`	`get_power_centers`
`GET`	`/community/{community_id}/power-topology`	`get_community_power_topology`
`GET`	`/community/{community_id}/signatures/{shape_type}`	`get_members_by_signature`
`GET`	`/constitutional/user/{user_did}`	`get_constitutional_properties`
`GET`	`/content/documents`	`list_content_documents`
`GET`	`/content/documents/{doc_id}`	`get_content_document`
`GET`	`/content/images`	`list_content_images`
`POST`	`/corpus/action`	`create_corpus_action`
`POST`	`/corpus/{user_did}/propose-action`	`corpus_propose_action`
`GET`	`/corpus/{user_did}/suggestions`	`get_corpus_suggestions`
`POST`	`/couplings/custom`	`create_custom_coupling`
`GET`	`/debug/manifold/{document_id}`	`debug_manifold`
`GET`	`/debug/manifolds`	`debug_manifolds`
`GET`	`/debug/state`	`debug_state`
`GET`	`/debug/unclassified-verbs`	`get_unclassified_verbs`
`POST`	`/debug/unclassified-verbs/export`	`export_unclassified_verbs`
`GET`	`/demo/coupling/{user_a}/{user_b}`	`get_demo_coupling`
`GET`	`/demo/discoveries/{name}`	`get_demo_discoveries`
`GET`	`/demo/lorentz`	`get_lorentz_demo`
`GET`	`/demo/manifest`	`get_demo_manifest`
`GET`	`/demo/user/{name}`	`get_demo_user`
`GET`	`/demo/user/{name}/compositions`	`get_demo_user_compositions`
`GET`	`/demo/user/{name}/sigma`	`get_demo_user_sigma`
`GET`	`/demo/user/{name}/trace`	`get_demo_user_trace`
`GET`	`/demo/users`	`get_demo_users`
`POST`	`/document`	`register_document`
`GET`	`/document/{document_id}/backforward`	`get_document_backforward`
`GET`	`/document/{document_id}/observation`	`get_document_observation`
`POST`	`/document/{document_id}/suggest`	`document_suggest`
`GET`	`/document/{document_id}/world-view`	`get_document_world_view`
`GET`	`/documents`	`list_documents`
`GET`	`/documents/{document_id}/semantic_neighbors`	`get_document_neighbors`
`POST`	`/extract_semantics`	`extract_semantics`
`GET`	`/field/user/{user_did}`	`get_user_field_state`
`GET`	`/gems`	`gem_viewer_page`
`GET`	`/gems/discover/{user_did}`	`discover_compatible_gems`
`GET`	`/gems/formation-state`	`get_gem_formation_state`
`GET`	`/gems/mine/{user_did}`	`get_my_gems`
`POST`	`/gems/{gem_id}/observe/{user_did}`	`observe_gem_with_contribution`
`POST`	`/gems/{gem_id}/publish/{user_did}`	`publish_gem`
`GET`	`/gems/{gem_id}/{user_did}`	`get_gem`
`GET`	`/health`	`health`
`GET`	`/history/artifact/{kind}/{sha256_hex}`	`get_history_artifact`
`POST`	`/history/stageA/checkpoint/anchor`	`stagea_checkpoint_anchor`
`GET`	`/history/stageA/checkpoint/{checkpoint_id}/{session_id}/{phase}`	`get_stagea_checkpoint`
`POST`	`/history/surplus/snapshot`	`snapshot_surplus`
`GET`	`/images/{image_id}`	`serve_image`
`POST`	`/learning/epigenetic/export`	`export_epigenetic_state`
`POST`	`/learning/epigenetic/inject-signal`	`inject_learning_signal`
`GET`	`/learning/epigenetic/state`	`get_epigenetic_state`
`GET`	`/learning/epigenetic/telomeres`	`get_epigenetic_telomeres`
`POST`	`/learning/epigenetic/thresholds`	`update_learning_thresholds`
`GET`	`/learning/epigenetic/window`	`get_learning_window_state`
`POST`	`/learning/epigenetic/window/transition`	`transition_learning_window`
`POST`	`/learning/export`	`export_learning_corpus`
`GET`	`/learning/layer/user/{user_did}/reachable`	`get_reachable_articulated`
`GET`	`/learning/layer/user/{user_did}/state`	`get_learned_state`
`GET`	`/learning/layer/user/{user_did}/trace`	`get_trace_articulation`
`GET`	`/learning/patterns`	`get_learning_patterns`
`GET`	`/learning/reintegration-queue`	`get_reintegration_queue`
`GET`	`/learning/signals`	`get_learning_signals`
`GET`	`/marginalia/comment/{comment_id}`	`get_marginalia_by_comment`
`GET`	`/marginalia/coupling/{coupling_id}`	`get_marginalia_by_coupling`
`GET`	`/marginalia/document/{document_id}`	`get_document_marginalia_summary`
`GET`	`/marginalia/session/{user_did}`	`get_session_marginalia_summary`
`GET`	`/marginalia/stats`	`get_marginalia_stats`
`GET`	`/marginalia/user/{user_did}`	`get_user_marginalia`
`GET`	`/marginalia/user/{user_did}/voice`	`get_user_voice_summary`
`POST`	`/observe`	`observe_compositional_action`
`GET`	`/observe/fresnel_zones/{document_id}`	`observe_fresnel_zones`
`GET`	`/observe/metric_tensor/{document_id}`	`observe_metric_tensor`
`GET`	`/observe/triangulate/{document_id}`	`observe_triangulated`
`POST`	`/observe_user_activity`	`observe_user_activity`
`GET`	`/overlay`	`overlay_dashboard_page`
`GET`	`/patterns/evolution`	`get_pattern_evolution`
`GET`	`/persona/{persona_id}`	`get_persona`
`GET`	`/personas`	`get_personas`
`POST`	`/perspective/z-depths`	`get_z_depths`
`GET`	`/polyworld/detect`	`detect_polyworlds`
`GET`	`/polyworld/dimensions`	`get_polyworld_dimensions`
`GET`	`/superposition/convergences`	`get_convergences`
`GET`	`/superposition/three-voice`	`three_voice_superposition`
`POST`	`/trace/entity-link`	`link_trace_entities`
`GET`	`/trace/search`	`search_traces`
`GET`	`/trace/search/events`	`search_trace_events`
`GET`	`/trace/{trace_id}`	`get_trace`
`GET`	`/traces/coupling`	`get_coupling_traces`
`GET`	`/traces/coupling_ud`	`get_coupling_ud_traces`
`GET`	`/traces/evolution/{user_did}`	`get_user_evolution`
`GET`	`/user/{user_did}/activities`	`get_user_activities`
`GET`	`/user/{user_did}/document/{document_slug}`	`get_user_document_by_slug`
`GET`	`/user/{user_did}/documents`	`get_user_documents`
`GET`	`/user/{user_did}/field_state`	`get_user_field_state`
`GET`	`/user/{user_did}/observation`	`get_user_corpus_observation`
`GET`	`/user/{user_did}/trajectory`	`get_user_trajectory`