OnlyWorlds Platform API
Facts about OnlyWorlds itself, such as its size. No credentials.
Facts about OnlyWorlds itself, such as its size. No credentials.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/onlyworlds-com:onlyworlds-com-platform-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: OnlyWorlds Platform API
version: '2.0'
description: 'The OnlyWorlds platform API: worlds of typed, linked elements (22 types), served
for any tool to read and write. Base URL: `https://www.onlyworlds.com/api/v2`. To try it, read the public demo world (Moppetopia) with `API-Key: 0000000001`. **Authentication** is header-based, per world. `API-Key` names the world
(a scoped `ow_r_`/`ow_w_` key from your account page, or a classic
10-digit key). Writes also need `API-Pin`: your 4-digit account PIN, or an
AI seat''s `ow_s_` secret. The key says which world, the PIN proves it''s you. Prefixed keys (`ow_r_`, `ow_w_`) read without it, and `ow_r_` read keys are made
for sharing; a classic key sends its PIN for reads too, on a public world as on a
private one (the demo worlds'' keys aside). **Keys and roles.** A world''s *owner* is the account that made it, and mints
its `ow_r_` (read) and `ow_w_` (write) keys. A *classic key* is the 10-digit key
every world had before prefixed keys; it acts as the owner. An `ow_a_` account
token is for the `/account` routes, and it also reads a world, read only: on
element get and list, search and the world GET, `world=` names the world, and
the token reads it as its account there (the owner the whole world, a member its
role''s view, anyone else what the public may read, a 404 on a world not open to
the public). Every route that takes it names `AccountToken` in its security. The
owner can invite *members*, each
with their own key and a role: `co_builder` (changes anything), `contributor`
(changes only what it created) or `guest` (sees only what it made, what its
Character is on or knows, and who is here, and knows of what its Character''s
own sheet links to, one step out, unless hidden: a stub of its name, description,
kind and picture (a Character''s also of its physicality, height, weight, species
and reputation), marked `known_of`; changes only what it made, and its
notes, Narratives, are told by its own Character). An *AI seat* is
a member that is a tool or an AI rather than a person: it redeems a join
code at `POST /join` for a key and an `ow_s_` secret (its `API-Pin`), or a person
in the world makes it for their own AI (`POST /account/worlds/{world_id}/seats`), and its
*sponsor* is the person who answers for it. **Who writes what.** A contributor writes only the elements its own membership
created (and, short of deleting it, the Character it plays when it holds the right
to change it, `may_change_character`, which the owner gives with that Character or
withholds); a guest the same; a co-builder writes every element; a write
to another''s element answers 403 `not_author`. A co-builder may also mint
contributor and guest invite links (`/links`) and change the world''s settings
(`PATCH /world`, all but `owner_character`); the public switch and co-builder
links stay the owner''s. **Who changed it.** Every element carries `changed_by` (the membership that
last changed it, null for the owner) and `changed_via`, the door it came
through: `seat` (an AI seat), `mcp`, `declared`, `api`, `v1`, `sync` or
`server`. A tool whose AI writes with a person''s key sends the header
`X-OW-Agent` (any value; it is never stored), and its writes read `declared`. `seat`, `mcp` and `declared` are the doors the platform marks as an AI''s. A client names itself with
the header `X-OW-Client` (`atlas`, `lantern`, `sdk`): lower case letters, digits
and hyphens, 1 to 32 characters. It is read on writes only and stored beside
the door, as `changed_client` (a delete''s `deleted_client` on `/changes`); a value
outside that rule is ignored, never refused. It is the client''s claim, never
proof, and it changes no door and no permission. **Limits.** Each key or account token may make 300 requests a minute, reads and
writes together (a `/bulk` call is one request), and a request with neither 60 a
minute per address. A practice world''s key is published, so it counts as the
address too (60 a minute, shared with your keyless reads), and one builder''s loop
never closes the door on another''s.'
x-ow-limits:
requests_per_minute:
value: 300
unit: requests
per: 60 seconds per key or account token
applies_to: 'Every route under /api/v2 but the health checks and some of the upload service''s own signed reports, reads and writes together; a /bulk call is one request. An OPTIONS request (a browser''s preflight) is not counted. The request budget is also spent by a request to the MCP server at /mcp, by a request to the metadata routes (/api/metadata/, /api/worldapi/metadata/) that names a world in ?world= and sends no API-Key, when it carries a Bearer token or keyless reading is switched on, and by requests to some of the site''s own pages. Over it: 429 too_many_requests.'
where: null
requests_per_minute_keyless:
value: 60
unit: requests
per: 60 seconds per address
applies_to: A request with no key and no account token.
where: null
changes_head_free_per_minute:
value: 120
unit: requests
per: 60 seconds per key or account token
applies_to: 'GET /changes?head=true answered 304: given back to the request budget, up to this many.'
where: null
server_busy_slots:
value: 6
unit: requests
per: server process
applies_to: Requests in flight at once on every route but the health checks; one past them waits for a slot.
where: null
server_busy_wait_seconds:
value: 10.0
unit: seconds
per: request
applies_to: How long a request waits for a slot before 503 server_busy.
where: null
request_body_bytes:
value: 2621440
unit: bytes
per: request
applies_to: 'A request''s body. Over it: 413 payload_too_large.'
where: null
bulk_items:
value: 1000
unit: items
per: request
applies_to: POST /bulk.
where: '#/paths/~1api~1v2~1bulk/post/requestBody/content/application~1json/schema/properties/items/maxItems'
list_limit_default:
value: 100
unit: elements
per: page
applies_to: GET /{type} with no limit.
where: '#/paths/~1api~1v2~1character/get/parameters/0/schema/default'
list_limit_max:
value: 1000
unit: elements
per: page
applies_to: GET /{type} limit; a larger one is read as this.
where: null
list_ids_max:
value: 200
unit: ids
per: request
applies_to: 'GET /{type} ids. More: 422.'
where: '#/paths/~1api~1v2~1character/get/parameters/10/schema/maxItems'
search_q_min_chars:
value: 2
unit: characters
per: request
applies_to: GET /search q.
where: '#/paths/~1api~1v2~1search/get/parameters/0/schema/minLength'
search_q_max_chars:
value: 200
unit: characters
per: request
applies_to: GET /search q.
where: '#/paths/~1api~1v2~1search/get/parameters/0/schema/maxLength'
search_limit_default:
value: 50
unit: results
per: request
applies_to: GET /search with no limit.
where: '#/paths/~1api~1v2~1search/get/parameters/2/schema/default'
search_limit_max:
value: 200
unit: results
per: request
applies_to: GET /search limit; a larger one is read as this.
where: null
changes_limit_default:
value: 500
unit: changes
per: page
applies_to: GET /changes with no limit.
where: '#/paths/~1api~1v2~1changes/get/parameters/1/schema/default'
changes_limit_max:
value: 1000
unit: changes
per: page
applies_to: 'GET /changes limit. More: 422.'
where: '#/paths/~1api~1v2~1changes/get/parameters/1/schema/maximum'
file_bytes:
value: 26214400
unit: bytes
per: file
applies_to: A file kept on an element.
where: null
files_world_bytes:
value: 262144000
unit: bytes
per: world
applies_to: All the files a world keeps, together.
where: null
file_tickets_per_day:
value: 200
unit: tickets
per: 24 hours per world
applies_to: 'File upload tickets. Over it: 429 quota_exceeded.'
where: null
mcp_read_file_bytes:
value: 65536
unit: bytes
per: call
applies_to: The text the MCP read_file tool returns in one call; past it the reply is cut there and marked truncated.
where: null
snapshot_world_bytes:
value: 104857600
unit: bytes
per: world
applies_to: 'A world''s daily file: a world whose file would be larger gets none, and its page says so.'
where: null
image_bytes:
value: 15728640
unit: bytes
per: image
applies_to: 'An image upload: the ticket''s max_bytes, which the upload host holds it to.'
where: null
image_account_bytes:
value: 1073741824
unit: bytes
per: account
applies_to: 'All the images an account has uploaded, together (the admin may raise one account''s). At it: 403 storage_full.'
where: null
image_tickets_per_day:
value: 200
unit: tickets
per: 24 hours per world
applies_to: 'Image upload tickets. Over it: 429 quota_exceeded.'
where: null
extensions_bytes:
value: 65536
unit: bytes
per: element
applies_to: 'An element''s extension fields together, as compact UTF-8 JSON; the world''s own store takes the same cap. Over it: 422.'
where: null
client_name_chars:
value: 32
unit: characters
per: request
applies_to: The X-OW-Client header. A longer value is no name, never a refusal.
where: null
idempotency_key_chars:
value: 200
unit: characters
per: request
applies_to: The Idempotency-Key header.
where: '#/paths/~1api~1v2~1character/post/parameters/0/schema/maxLength'
idempotency_key_seconds:
value: 86400
unit: seconds
per: key
applies_to: How long a key's first answer is kept and replayed.
where: null
proposal_evidence_chars:
value: 2000
unit: characters
per: proposal
applies_to: A proposal's evidence.
where: '#/paths/~1api~1v2~1character~1{id}~1proposals/post/requestBody/content/application~1json/schema/properties/evidence/maxLength'
proposal_reason_chars:
value: 2000
unit: characters
per: request
applies_to: A keeper's reason, declining a proposal or reviewing an element.
where: '#/paths/~1api~1v2~1character~1{id}~1proposals~1{pid}~1decline/post/requestBody/content/application~1json/schema/properties/reason/maxLength'
proposal_expires_min_days:
value: 1
unit: days
per: proposal
applies_to: A proposal's expires, from now.
where: null
proposal_expires_max_days:
value: 365
unit: days
per: proposal
applies_to: A proposal's expires, from now.
where: null
proposal_expires_default_days:
value: 30
unit: days
per: proposal
applies_to: A proposal sent with no expires.
where: null
proposals_open_per_element:
value: 5
unit: proposals
per: proposer per element
applies_to: 'Open proposals. Over it: 422 too_many_open.'
where: null
proposals_open_per_world:
value: 50
unit: proposals
per: proposer per world
applies_to: 'Open proposals. Over it: 422 too_many_open.'
where: null
proposals_marked_listed:
value: 500
unit: elements
per: request
applies_to: 'GET /world/proposals: the newest marked new elements it lists.'
where: null
proposals_list_limit_default:
value: 100
unit: proposals
per: page
applies_to: GET /world/proposals and GET /{type}/{id}/proposals with no limit.
where: '#/paths/~1api~1v2~1world~1proposals/get/parameters/3/schema/default'
proposals_list_limit_max:
value: 1000
unit: proposals
per: page
applies_to: GET /world/proposals and GET /{type}/{id}/proposals limit.
where: '#/paths/~1api~1v2~1world~1proposals/get/parameters/3/schema/maximum'
link_expiry_days:
value:
- 1
- 7
- 30
unit: days
per: link
applies_to: 'A link''s days: one of these.'
where: '#/paths/~1api~1v2~1links/post/requestBody/content/application~1json/schema/properties/days/enum'
link_expiry_default_days:
value: 7
unit: days
per: link
applies_to: A link sent with no days.
where: null
link_max_uses:
value: 50
unit: uses
per: link
applies_to: 'A person''s or a player''s link: how many people it lets in.'
where: '#/paths/~1api~1v2~1links/post/requestBody/content/application~1json/schema/properties/max_uses/maximum'
pending_invites:
value: 50
unit: invites
per: world
applies_to: 'Pending email invites and person and player links that can still be used: a new person or player link counts them together; a new email invite counts the email invites alone. AI links count under agent_seats, not here.'
where: null
agent_seats:
value: 50
unit: agents
per: world
applies_to: AI seats and AI links that can still be used, together.
where: null
signin_state_chars:
value: 1024
unit: characters
per: request
applies_to: A sign-in request's state.
where: null
signin_verifier_min_chars:
value: 43
unit: characters
per: request
applies_to: POST /auth/token code_verifier.
where: '#/paths/~1api~1v2~1auth~1token/post/requestBody/content/application~1json/schema/properties/code_verifier/minLength'
signin_verifier_max_chars:
value: 128
unit: characters
per: request
applies_to: POST /auth/token code_verifier.
where: '#/paths/~1api~1v2~1auth~1token/post/requestBody/content/application~1json/schema/properties/code_verifier/maxLength'
signin_code_seconds:
value: 60
unit: seconds
per: code
applies_to: A sign-in code, single use.
where: null
signin_token_lifetime_max_hours:
value: 720
unit: hours
per: token
applies_to: A registered tool's own token lifetime.
where: null
signin_attempts:
value: 40
unit: requests
per: 300 seconds per address
applies_to: 'POST /auth/token and the password sign-in, one count. Over it: 429 rate_limited.'
where: null
servers:
- url: https://www.onlyworlds.com
description: OnlyWorlds
tags:
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://artifacts.apis.io/onlyworlds-com/openapi/onlyworlds-com-platform-api-openapi.yml