---
title: "Preview a join code without using it"
method: POST
path: "/api/v2/join/preview"
tags: ["Join"]
---

# Preview a join code without using it

`POST /api/v2/join/preview`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/join/preview`
- Auth: none required

Who invites the agent, to which world, before it redeems. Writes
nothing; every bad code answers exactly as the redeem does.

## Request body

- object
  - `code` string, required: The ow_j_ join code.

## Response `200`

The invitation the code holds, without using it: `reader` (`agent`: redeem it here at POST /join; `person`: a signed-in account accepts it at POST /account/join; `player`: redeem it at POST /join with no account for a read key), `world` {name, description}, `invited_by` (the name the inviter gave, unchecked, or null), `owner_character` (the name of the Character the world's owner chose as theirs, or null when none is set), `role` (always guest for a player), `with_character` (agents: true means redeeming gives you a Character in the world; false, you join without one; always false for a person, always true for a player), and `expires_at` (ISO 8601, UTC). A table link (a player code that works several times) adds `max_uses`, `uses_left`, `name_required` and `characters`, the owner's list in its order, each {id, name, image_url, taken}; a link for one answers without them. The code stays unused.

- object
  - `reader` 'agent' | 'person' | 'player', required
  - `world` object, required
    - `name` string, required
    - `description` string, required
  - `invited_by` string, nullable, required
  - `owner_character` string, nullable, required
  - `role` string, required
  - `with_character` boolean, required
  - `expires_at` string, date-time, required
  - `max_uses` integer: A table link only: how many times the link works.
  - `uses_left` integer: A table link only: how many places are left.
  - `name_required` boolean: A table link only: true when the owner listed no Characters, so each player sends a `name` and gets a fresh Character with it.
  - `characters` object[]: A table link only: the Characters a player may pick, in the owner's order. `taken` is true while a live seat in the world plays it (a screen keeps the order and puts taken ones last). A Character hidden or deleted since the link was made is left out.
    - `id` string, uuid, required
    - `name` string, required
    - `image_url` string, nullable, required
    - `taken` boolean, required

## Other responses

- `404`: The code is not valid: unknown, used, revoked or expired (not_found). The same answer, byte for byte, as POST /join gives.
- `422`: The body is missing or not a JSON object.
- `429`: Too many requests: over the request budget (code too_many_requests, type rate_limited): 300 requests a minute per key or account token, 60 a minute per address for a request with neither. Retry after the Retry-After header's seconds.
- `503`: The server is busy: every request slot stayed full for 10 s (code server_busy, type api_error). Retry after the Retry-After header's seconds.

## Changes

- **2026-10-20** `78df39c4c62e`: 4 warning
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `404`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `422`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `429`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `503`
- **2026-10-20** `4dd5b1cd0687`: 8 warning, 4 info
  - added the new `character_taken` enum value to the `error/code` response property for the response status `404`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `422`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `429`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `503`
  - …8 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/join/preview/post.md)

---

[API](https://skmtc.dev/onlyworlds/apis/onlyworlds-api.md) · [All operations](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/revisions/78df39c4c62e?raw)