tangl.rest

The REST server is the transport-facing wrapper around tangl.service.ServiceManager.

  • tangl.rest.app is the outer FastAPI application.

  • tangl.rest.api_server is mounted at /api/v2.

  • The mounted API’s OpenAPI document is served at /api/v2/openapi.json.

  • Use tangl.service methods for service-method semantics; use this page for HTTP route inventory and app bootstrap details.

Related design docs

Routes

POST /story/apply

Apply a debug expression in the active story context.

Handler:

tangl.rest.routers.restricted_routes.apply_effect_post

Tags:

Story, Restricted

Operation id:

apply_effect_post

PUT /story/apply

Compatibility alias for POST /story/apply.

Handler:

tangl.rest.routers.restricted_routes.apply_effect_put

Tags:

Story, Restricted

Operation id:

apply_effect_put

POST /story/check

Evaluate a debug expression in the active story context.

Handler:

tangl.rest.routers.restricted_routes.check_expression

Tags:

Story, Restricted

Operation id:

check_expression

POST /story/do

Resolve a player choice and return the updated runtime envelope.

Handler:

tangl.rest.routers.story_router.do_story_action

Tags:

Story

Operation id:

do_story_action

DELETE /story/drop

End the user’s active story and optionally archive the ledger.

Handler:

tangl.rest.routers.story_router.reset_story

Tags:

Story

Operation id:

reset_story

PUT /story/go

Jump the active frame to block_id.

Handler:

tangl.rest.routers.restricted_routes.goto_story_block

Tags:

Story, Restricted

Operation id:

goto_story_block

GET /story/info

Return runtime status details for the active story.

Handler:

tangl.rest.routers.story_router.get_story_info

Tags:

Story

Operation id:

get_story_info

GET /story/inspect

Return debug inspection info for the active node (or a specific node).

Handler:

tangl.rest.routers.restricted_routes.inspect_story_node

Tags:

Story, Restricted

Operation id:

inspect_story_node

POST /story/story/create

Create a story session and return the initial runtime envelope.

Handler:

tangl.rest.routers.story_router.create_story

Tags:

Story

Operation id:

create_story

GET /story/update

Return the runtime envelope with ordered fragments.

Handler:

tangl.rest.routers.story_router.get_story_update

Tags:

Story

Operation id:

get_story_update

GET /system/info

Return high-level information about the running service.

Handler:

tangl.rest.routers.system_router.get_system_info

Tags:

System

Operation id:

get_system_info

PUT /system/reset

System resets are not wired through the orchestrator yet.

Handler:

tangl.rest.routers.restricted_routes.reset_system

Tags:

System, Restricted

Operation id:

reset_system

GET /system/secret

Encode secret as an API key for clients.

Handler:

tangl.rest.routers.system_router.get_key_for_secret

Tags:

System

Operation id:

get_key_for_secret

GET /system/worlds

List the available worlds registered with the service.

Handler:

tangl.rest.routers.system_router.get_worlds

Tags:

System

Operation id:

get_worlds

POST /user/create

Create a user and return the secret metadata for clients.

Handler:

tangl.rest.routers.user_router.create_user

Tags:

User

Operation id:

create_user

DELETE /user/drop

Remove the authenticated user and purge persisted resources.

Handler:

tangl.rest.routers.user_router.drop_user

Tags:

User

Operation id:

drop_user

GET /user/info

Return profile information for the authenticated user.

Handler:

tangl.rest.routers.user_router.get_user_info

Tags:

User

Operation id:

get_user_info

PUT /user/secret

Update the secret for the authenticated user and surface the new API key.

Handler:

tangl.rest.routers.user_router.update_user_secret

Tags:

User

Operation id:

update_user_secret

PUT /user/world

Linking users to worlds is not yet implemented in the REST API.

Handler:

tangl.rest.routers.user_router.set_user_world

Tags:

User

Operation id:

set_user_world

GET /world/{world_id}/info

Return metadata describing world_id.

Handler:

tangl.rest.routers.world_router.get_world_info

Tags:

World

Operation id:

get_world_info

GET /world/{world_id}/preflight

Return non-mutating authoring diagnostics for world_id.

Handler:

tangl.rest.routers.world_router.preflight_world

Tags:

World

Operation id:

preflight_world

GET /world/{world_id}/scenes

Scene listing is not yet exposed through the orchestrated REST API.

Handler:

tangl.rest.routers.restricted_routes.get_scene_list

Tags:

World, Restricted

Operation id:

get_scene_list

Application bootstrap

FastAPI API, media, and docs server for StoryTangl narrative engine.

`bash $ tangl-serve ` or

`bash $ python -m tangl.rest `

or

`bash $ uvicorn tangl.rest.app:app `

Default mounts: - api: /api/v2 - spec: /api/v2/openapi.json - docs: /docs - media: /media

FastAPI api server for StoryTangl narrative engine.

REST service-manager dependencies and auth helpers.

get_service_manager()[source]

Return the process-wide service-manager singleton.

get_user_locks()[source]

Provide per-user asyncio locks for story routes.

resolve_user_auth(api_key, *, service_manager=None)[source]

Resolve API key to user auth context for route handlers.

require_service_access(method_name, *, user_auth=None)[source]

Enforce service-method access metadata for transport calls.

reset_service_manager_for_testing()[source]

Reset cached service-manager singleton (testing hook).