--- title: "Get one collective" method: GET path: "/api/v2/collective/{id}" tags: ["Collective"] --- # Get one collective `GET /api/v2/collective/{id}` ## Request - Base URL: `https://www.onlyworlds.com` - URL: `https://www.onlyworlds.com/api/v2/collective/{id}` - Auth: one of: - API key in header `API-Key` - API key in header `API-Key` and API key in header `API-Pin` ## Path parameters - `id` string, uuid, required ## Query parameters - `expand` string[] - `fields` string[] - `as` string ## Response `200` The element. With `?fields=` the body holds only the named keys (not this schema's required set); with `?expand=` each named link holds ElementStub objects instead of ids. - Collective: A collective as the API returns it. Single links are an id or null, multi links an array of ids; extension fields appear inline. `?fields=` returns only the named keys, and `?expand=` replaces the named links' ids with ElementStub objects. - `type` 'collective', required - `id` string, uuid, required - `name` string, required: Name of the element. - `description` string, required: Any kind of details about the element. - `supertype` string, required: The top level category to which the element belongs. - `subtype` string, required: The sub level category through which the element is further classified. - `image_url` string, required: URL to an image representing the element. - `composition` string, required: Internal structure or demographic makeup of the collective. - `activity` string, required: Primary behaviors or actions the collective engages in. - `disposition` string, required: Emotional control or volatility expressed by the collective. - `state` string, required: Current condition or operational status of the collective. - `count` integer, nullable, required: Number of members in the collective (approximate or exact). - `formation_date` integer, nullable, required: Date the collective was formed, using world TIME units. - `operator` string, uuid, nullable, required: Institution that manages or directs the collective. An Institution's id. - `equipment` string[], required: Tools or gear in possession of and/or regularly used by the collective. Object ids. - `abilities` string[], required: Abilities commonly shared among members of the collective, or abilities of that collective as a whole. Ability ids. - `symbolism` string[], required: Cultural expressions, rituals, or symbols that unify or distinguish the collective. Construct ids. - `species` string[], required: Species that compose or participate in the collective. Species ids. - `characters` string[], required: Characters who are members of the collective. Character ids. - `creatures` string[], required: Creatures associated with or included in the collective. Creature ids. - `phenomena` string[], required: Phenomena that influence or characterize the collective. Phenomenon ids. - `created_at` string, date-time, required - `updated_at` string, date-time, required - `change_seq` integer, required: The world change sequence at this element's last write. - `created_by` string, uuid, nullable, required: The world membership that created this element, or null when the world's owner did. - `changed_by` string, uuid, nullable, required: The world membership that last changed this element, or null when the world's owner (or the server) did, or no write has touched it since doors were recorded. - `changed_via` 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | 'null', nullable, required: The door of the last change: `seat` (an agent seat), `mcp` (the MCP server), `declared` (the request sent an X-OW-Agent header), `api`, `v1`, `sync` (the mobile app's sync) or `server` (the server, on its own behalf). The first three mean an agent made it. Null: no write since doors were recorded. - `known_of` true: Present, and true, only on an element this reader knows of but does not see whole: a guest or player reaches it only because its own Character's sheet links to it (one step out). Such a row keeps `id`, `type`, `name`, `description`, `supertype`, `subtype`, `image_url`, `created_at`, `updated_at` and `change_seq`, and its type's public fields (none for a collective); every other field reads as unset (text "", numbers and single links null, multi links [], `created_by`, `changed_by` and `changed_via` null, no extension fields), its files are 404, and search matches only what it keeps. Absent: the element is whole. Any other grant (it names the reader's Character, the reader knows it, it is on the roster, the reader made it) makes it whole; a hidden element is never even a stub, whatever its public fields. Read-only: a write carrying `known_of` is refused (`known_of_not_writable`). ## 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). - `404`: Not found in this world (not_found). - `410`: Deleted: this world once held the element and deleted it (code gone, type not_found). The body carries the envelope and, beside it, the deletion's `change_seq` and `deleted_at`. An id never seen here, or deleted in another world, is a 404. - `422`: Invalid request: an unknown or malformed query parameter, cursor or id (invalid_request); `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** `78df39c4c62e`: 7 warning - added the new `known_of_not_writable` enum value to the `allOf[subschema #1: Error]/error/code` response property for the response status `410` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `401` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `403` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `404` - …3 more - **2026-10-20** `4dd5b1cd0687`: 14 warning, 1 info - added the new `character_taken` enum value to the `allOf[subschema #1: Error]/error/code` response property for the response status `410` - 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 `404` - …11 more [Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/collective/:id/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/1752622ae8ce?raw)