---
title: "Search a world's elements by the words in their text"
method: GET
path: "/api/v2/search"
tags: ["Search"]
---

# Search a world's elements by the words in their text

`GET /api/v2/search`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/search`
- Auth: one of:
  - API key in header `API-Key`
  - API key in header `API-Key` and API key in header `API-Pin`

Every element of the world whose `name` or text fields (`description` and the type's other prose fields, such as a Character's `background`; not supertype, subtype or image_url) hold every word of `q` as a whole word, ignoring case: `ore` does not find `more`, and `copper mine` needs both words somewhere in the element. No stemming. A guest key searches only what it may read.

## Query parameters

- `q` string, required
- `type` 'ability' | 'collective' | 'character' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone'
- `limit` integer
- `as` string

## Response `200`

The matching elements, name matches first.

- SearchResults: The elements whose name or text holds every word of `q`.
  - `query` string, required: `q` as searched (trimmed).
  - `results` object[], required: Name matches first, then the rest; inside each, by type (the API's type order), then alphabetical by name.
    - `type` 'ability' | 'collective' | 'character' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone', required
    - `id` string, uuid, required
    - `name` string, required
    - `supertype` string, required
    - `subtype` string, required
    - `field` string, required: Where the words were found: `name`, or the first text field (in the type's schema order) that holds them all, else the first that holds any.
    - `snippet` string, required: Up to 160 characters of that field around the first match, as plain text (runs of whitespace shown as one space, no markup).
  - `count` integer, required: How many results came back.
  - `truncated` boolean, required: True when more elements matched than `limit` let through. There are no further pages: narrow `q` or `type`, or raise `limit`.

## Other responses

- `401`: Missing, invalid or revoked credential, or a wrong PIN (authentication_error; code key_revoked for a revoked key, invalid_credentials otherwise).
- `403`: A member key sent `as`: view as is the owner's (view_as_owner_only).
- `422`: Invalid request (invalid_request): `q` missing, under 2 or over 200 characters, or holding no word; an unknown `type`; a `limit` that is not an integer; or a query parameter other than q, type, limit. `param` names the culprit.
- `429`: Too many failed PIN attempts; see the Retry-After header (rate_limited). Or 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** `4dd5b1cd0687`: 10 warning
  - added the new `character_taken` enum value to the `error/code` response property for the response status `401`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `403`
  - 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`
  - …6 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/search/get.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/4dd5b1cd0687?raw)