API

Overview

All endpoints share the same base URL and conventions:

• Base URL: https://api.unofficial.voyage
• CORS: open to all origins — safe to call from any web page, terminal, or agent runtime.
• Auth: none. The wiki is a public reference.
• Versioning: every endpoint serves the currently deployed wiki. The validator endpoint returns its validatorVersion in the response body.

Quick reference

POST /validate

Validates a world JSON against the live V34 schema plus every semantic check the in-browser Validator performs — cross-references, enum validity, size limits, runtime-affecting authoring patterns. Output is identical to the in-browser tool.

Request

• Content-Type: application/json
• Body: the world JSON object (the same JSON you would paste into the Voyage editor).

Response

JSON object with:

• counts — { errors, warnings, recommendations } totals.
• errors — array of { path, title, fix, detail?, value?, message }. Will break at runtime — broken references, invalid enums, codec shape violations.
• warnings — array of the same shape. Might break at runtime — behaviour degraded, fragile, or silently wrong.
• recommendations — array of the same shape. Might improve quality — missing optional context the AI would benefit from. Safe to ignore by design.
• validatorVersion — ISO-8601 timestamp of the currently deployed validator.

Example (curl)

curl -X POST https://api.unofficial.voyage/validate \
  -H 'Content-Type: application/json' \
  --data-binary @MyWorld.json

Example (JavaScript)

const result = await fetch('https://api.unofficial.voyage/validate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(world),
}).then(r => r.json());

console.log(result.counts);
result.errors.forEach(({ path, message }) => console.log(path, message));

Example (Python)

import json, urllib.request

with open('MyWorld.json', 'rb') as f:
    body = f.read()

req = urllib.request.Request(
    'https://api.unofficial.voyage/validate',
    data=body,
    headers={'Content-Type': 'application/json'},
)
result = json.loads(urllib.request.urlopen(req).read())
print(result['counts'])

GET /sections.json

Lightweight index of every documented section — section key, title, tab, summary. No body content. Good for an agent to enumerate before fetching specific sections.

curl https://api.unofficial.voyage/sections.json

GET /sections/<section>.json or .md

One section, fully self-contained. The .json form returns structured data; the .md form returns Markdown formatted for direct ingestion by an LLM. Both contain section metadata, the full prose body, per-field notes, and the V34 schema fragment for that section.

curl https://api.unofficial.voyage/sections/npcs.json
curl https://api.unofficial.voyage/sections/locations.md

GET /wiki.json or .md

The entire wiki in one payload — useful when an agent wants the full V34 reference loaded into its context in a single request. The Markdown form is typically the better fit for LLM ingestion.

curl https://api.unofficial.voyage/wiki.json
curl https://api.unofficial.voyage/wiki.md

GET /schema.json

Raw V34 codec schema as JSON — the same schema fragments embedded in the section endpoints, aggregated.

curl https://api.unofficial.voyage/schema.json

Agent prompt snippet

Drop this into your agent's system prompt or task instructions so it validates as it works:

You are authoring or editing a Voyage Heroes V34 world JSON.

Reference docs: every wiki section is available as a self-contained
endpoint at https://api.unofficial.voyage/sections/<section>.md or .json. Fetch only the
sections you need, or pull the whole wiki from https://api.unofficial.voyage/wiki.md in one request.

Verification: POST the JSON to https://api.unofficial.voyage/validate. The response groups
issues by severity:

  - errors: runtime-affecting problems. Fix these.
  - warnings: quality issues. Many are intentional; read the
    "Safe to ignore when..." line 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.

Conventions and notes

• Backtick chips in messages. Validator messages use backtick-wrapped tokens to mark field names and values, so agents can parse them as code-like literals.
• Path notation. Validator path values use dot/bracket notation into the world JSON — e.g. locations.Acorn Hall.factions[0], npcs.Maren Halst.type.
• Identical surfaces. The in-browser validator and this endpoint share the same engine. Output is identical across both.
• No write endpoints. The wiki is read-only. Validation does not modify the submitted JSON.