onlyworlds-api

OnlyWorlds API

Read and write world data via the OnlyWorlds REST API.

Teach v2. Every fresh example here uses /api/v2/ and /api/v2/bulk. The v2 surface returns real pagination, flat UUID link arrays, native creates, and honest Stripe-style errors that name the problem. The older v1 "classic" dialect still serves forever, but it has traps v2 doesn't — it lives in one clearly-marked Classic API section at the end. If you're writing new code, stay in v2.

Quick Reference (v2)

Operation	Method	Endpoint
Health check	GET	/api/v2/health
Get world info	GET	/api/v2/world
Update world meta (partial)	PATCH	/api/v2/world
List elements by type	GET	/api/v2/{type}
Get specific element	GET	/api/v2/{type}/{uuid}
Create element	POST	/api/v2/{type}
Update element (partial)	PATCH	/api/v2/{type}/{uuid}
Delete element	DELETE	/api/v2/{type}/{uuid}
Bulk upsert (standard upload path)	POST	/api/v2/bulk
Sync changes since cursor	GET	/api/v2/changes
Field descriptors for a type	GET	/api/metadata/{type}/

Endpoint names are SINGULAR — /character, /location, /institution. NOT plural.

Link fields are FLAT UUID arrays, both directions — read AND write use the bare field name (friends, species, objects), holding raw UUID strings. There is no _id/_ids suffix in v2. (The suffix is a v1-only thing — see Classic section. Sending friends_ids to v2 or /bulk is a hard 422 Unknown field: friends_ids, the #1 new-user error.)

Critical Rules

1. Read before PATCH. PATCH replaces the fields you send — for link arrays and text fields, it does not merge. To add a link or append text, GET the current value first, build the full new value, then PATCH it. GET is cheap; overwriting an array with a partial one is permanent data loss.
2. Verify after write. GET the element back after a create or update and confirm the fields landed. Cheap insurance on any batch.
3. /bulk is the standard upload path for parse results. One request, mixed types, per-item results, idempotent retry. Don't loop hundreds of individual POSTs — see Bulk Upload.
4. Mint your own UUIDs on create. IDs are UUIDv7 (time-sortable). Client-minted IDs let you reference an element you're creating in the same bulk batch (forward sibling refs are legal — no topological pre-sorting needed) and make retries idempotent. Generate a v7 UUID per element before upload.
5. Read the error envelope. The API now tells you exactly what's wrong (unknown field, dangling link, bad credentials) with a code, message, param, and doc_url. Don't guess — read the message. See Error Handling.