# World API

Use HTTP when a program must read or change a world. Use the application to build in the browser. Use Agent Integration when an outside model answers authorized turns.

## Authentication

Requests use `Authorization: Bearer <token>`. Tokens belong to a workspace. Read operations require `world.read`; edits require `world.write`. Use the URL of your Exulanica server. For a local installation:

```bash
export EXULANICA_API_URL="http://127.0.0.1:8000"
# Set EXULANICA_TOKEN to the token issued by your server operator.
```

The `/openapi.json` on your running server describes that installation. [Download the pinned OpenAPI schema](/openapi.json).

## Worldbuilding

Create or reopen a world, then keep the world ID the later routes require.

- [List Worlds](/docs/world-api/list-worlds): GET /worlds. Return the worlds in your workspace.

- [List Recipes](/docs/world-api/recipes): GET /worlds/recipes. Return the server’s world recipes.

- [Generate a World](/docs/world-api/generate): POST /worlds/generated. Generate and save a world from a recipe.

- [List Saved Entries](/docs/world-api/entries): GET /world-entries. Read the saved entries your workspace can reopen.

## World Structure

Read the version, discover what it supports, then edit against the current state digest.

- [Read a Version](/docs/world-api/version): GET /world/versions/{version_id}. Read authored state and retain state_sha256 before editing.

- [Read Capabilities](/docs/world-api/capabilities): GET /world/versions/{version_id}/capabilities. Discover supported operations for this version.

- [Place an Object](/docs/world-api/objects): POST /world/versions/{version_id}/objects. Place a catalog asset against the current digest.

## Models and Decisions

Read the roles a world offers, the society attached to a version, and the history those decisions recorded.

- [List Decision Roles](/docs/world-api/models): GET /world/versions/{version_id}/models. Read roles, offered models, and current choices.

- [Read Society State](/docs/world-api/society): GET /world/versions/{version_id}/society. Read the society attached to this version.

- [Read Recorded History](/docs/world-api/replay): GET /world/versions/{version_id}/society/replay. Replay stored decisions without a model call.

## Read Before You Write

List the workspace’s worlds, read its saved entry and version, then discover capabilities. Retain the state digest before editing. Inspect the saved state after a lost connection before retrying a write.

[Errors and Recovery](/docs/errors)

[Export and Portability](/docs/portability)