# Unofficial Voyage

Community schema reference and tools for Voyage Heroes world authors and the AI agents that help them.

- Human documentation: https://wiki.unofficial.voyage/
- World builder app: https://builder.unofficial.voyage/
- API documentation with examples: https://wiki.unofficial.voyage/tools/api

## Machine-readable API

Base URL: https://api.unofficial.voyage

Reference docs (GET, returns JSON or Markdown):
- https://api.unofficial.voyage/: This manifest
- https://api.unofficial.voyage/sections.json: Lightweight index of all sections
- https://api.unofficial.voyage/sections/<section>.json: One section - metadata + prose blocks + field explanations + schema fragment (JSON)
- https://api.unofficial.voyage/sections/<section>.md: One section - same content as JSON, formatted as Markdown
- https://api.unofficial.voyage/wiki.json: Entire wiki - all sections aggregated (JSON)
- https://api.unofficial.voyage/wiki.md: Entire wiki - all sections concatenated (Markdown)
- https://api.unofficial.voyage/schema.json: Raw schema JSON

Validation (POST world JSON, returns errors/warnings/recommendations):
- https://api.unofficial.voyage/validate: same checks as the in-browser validator; returns { counts, errors, warnings, recommendations, validatorVersion }

Legacy paths: https://unofficial.voyage/api/* permanently redirects to the matching https://api.unofficial.voyage/* endpoint. Follow redirects, or use the base URL above directly.

## Agent guidance

When authoring or editing a Voyage Heroes world JSON:

- Fetch only the sections you need from /sections/<section>.md, or pull the whole reference from /wiki.md in one request.
- Verify the world by POSTing it to /validate. The response groups issues by severity:
  - errors: runtime-affecting problems. Fix these. The Voyage editor publishes worlds with errors intact, but the engine silently drops fields or breaks lookups at runtime.
  - warnings: quality issues. Many are intentional design choices; read the "Safe to ignore when..." line in each message before acting.
  - recommendations: best-practice suggestions, same rule as warnings.
- Validate after each batch of changes. Do not declare work complete until counts.errors is 0.