OnlyWorlds Search API

Find elements by the words in their name and text.

GitHub OpenAPI

Operations 1

GET /api/v2/search Search a world's elements by the words in their text #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/onlyworlds-com:onlyworlds-com-search-api"
All apis
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.

Get an API 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 Specification

onlyworlds-com-search-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: OnlyWorlds Search 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 (74 KB total) ---
# Full source: https://artifacts.apis.io/onlyworlds-com/openapi/onlyworlds-com-search-api-openapi.yml