Worlds
Operations for Decentraland Worlds - privately owned virtual spaces that exist outside Genesis City. Worlds can be accessed via unique URLs and have their own rules and configurations.
Retrieve a paginated list of Decentraland Worlds with filtering and sorting.
Worlds vs Places: Worlds are privately owned virtual spaces accessed via unique URLs, while Places are scenes in Genesis City at specific coordinates.
Common Queries:
Most active worlds:
?order_by=most_activeSearch by name:
?search=partySpecific worlds:
?names=world-name-1&names=world-name-2
Maximum number of worlds to return (max 100)
100Number of worlds to skip for pagination
0Filter by specific world names (exact match, case-insensitive). Multiple names return worlds matching ANY name (OR logic).
["my-world","art-space"]Show only worlds marked as highlighted by moderators
falseExample: falseShow only worlds the automated daily ranking is not allowed to touch. Those worlds are listed normally by every other query; this is how to audit which ones carry the exclusion, since the catalogue is far larger than the page limit and scanning it would miss them.
falseExample: falseShow only authenticated user's favorite worlds (requires auth)
falseSort worlds by:
like_score: Best rated (VP-weighted, default)most_active: Current user countcreated_at: Newest first
like_scorePossible values: Sort direction
descPossible values: Full-text search in world title, description (min 3 chars)
Filter by categories
Include disabled/opt-out worlds in results
falseFilter by owner's Ethereum address
^0x[a-fA-F0-9]{40}$Worlds retrieved successfully
trueTotal number of worlds matching the query
42Bad request - Invalid parameters or malformed request
GET /api/worlds HTTP/1.1
Host: places.decentraland.org
Accept: */*
{
"ok": true,
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"title": "text",
"description": "text",
"image": "https://example.com",
"owner": "text",
"positions": [
"text"
],
"base_position": "text",
"contact_name": "text",
"contact_email": "text",
"content_rating": "text",
"likes": 1,
"dislikes": 1,
"like_score": 1,
"like_rate": 1,
"ranking": 0,
"highlighted": true,
"exclude_from_ranking": false,
"favorites": 1,
"disabled": true,
"disabled_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"deployed_at": "2026-01-01T00:00:00.000Z",
"user_like": true,
"user_dislike": true,
"user_favorite": true,
"user_count": 1,
"user_visits": 1,
"creator_address": "text",
"sdk": "7",
"connected_addresses": [
"text"
]
}
],
"total": 42
}Update the ranking score for a world. Requires service token authentication.
This is the endpoint that moves a world in browse. Worlds are ordered by their own ranking column, which is not the same column as a place's: writing to PUT /places/{place_id}/ranking for the place row that backs a world succeeds and changes nothing in browse. Address a world by its name, lowercased, which is its id.
Higher ranking values appear first, after highlighted worlds. Send null to remove the ranking.
Authentication: Accepts the value of either the DATA_TEAM_AUTH_TOKEN or the PLACES_ADMIN_AUTH_TOKEN environment variable in the Authorization header.
Curated rankings are editorial. Two states make a ranking off limits to the data team token, which gets a 403: while a world is highlighted its ranking is the order the curated shelf is shown in, and a world carrying exclude_from_ranking must stay browsable while the automated score leaves it alone.
Pre-configured service token for service-to-service authentication.
This authentication method is used for internal service calls, such as
the data team's ranking updates. The token value must match either the
DATA_TEAM_AUTH_TOKEN or the PLACES_ADMIN_AUTH_TOKEN environment
variable configured on the server.
To authenticate:
Include in requests: Authorization: Bearer <service-token> or Authorization: <service-token>
World id, which is the world name lowercased (for example gather.dcl.eth)
Ranking score for ordering places. Higher values appear first in listings (after highlighted places). Set to null to remove ranking.
0.85Ranking updated successfully
A Decentraland World - privately owned virtual space
Unique world identifier
World name
World description
World thumbnail URL
Owner's Ethereum address
Coordinate placeholders (worlds don't use Genesis City coordinates)
Base coordinate placeholder
^-?\d{1,3},-?\d{1,3}$Content rating
External ranking value for custom ordering
0True if this world is highlighted/featured by administrators
True if the automated discovery score must not rank this entity. It stays browsable
and keeps appearing in listings; only the scheduled scoring job is refused, with a
403 on the ranking endpoint. Distinct from highlighted, which moves where the
entity shows, and from hidden and disabled, which take it out of browse and out
of the catalogue. Survives a redeployment.
falseExample: falseTrue if world opted out of listing
Current users in the world
Visits in last 30 days
The creator's wallet address
^0x[a-fA-F0-9]{40}$SDK/runtime version (e.g., "7" for SDK7)
7List of wallet addresses currently connected to this world.
Only included when with_connected_users=true query parameter is set.
Invalid body, for example a missing ranking field
Unauthorized - Missing or invalid authentication token
The ranking is editorial and the data team token may not change it
Resource not found - Place/world doesn't exist or is disabled
PUT /api/worlds/{world_id}/ranking HTTP/1.1
Host: places.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"ranking": 1800
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"title": "text",
"description": "text",
"image": "https://example.com",
"owner": "text",
"positions": [
"text"
],
"base_position": "text",
"contact_name": "text",
"contact_email": "text",
"content_rating": "text",
"likes": 1,
"dislikes": 1,
"like_score": 1,
"like_rate": 1,
"ranking": 0,
"highlighted": true,
"exclude_from_ranking": false,
"favorites": 1,
"disabled": true,
"disabled_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"deployed_at": "2026-01-01T00:00:00.000Z",
"user_like": true,
"user_dislike": true,
"user_favorite": true,
"user_count": 1,
"user_visits": 1,
"creator_address": "text",
"sdk": "7",
"connected_addresses": [
"text"
]
}Mark a world as browsable but out of reach of the automated discovery score. Same semantics as the places endpoint: the world keeps appearing in listings and only the scheduled scoring job is refused, with a 403 on the world ranking endpoint.
Setting the exclusion also clears the stored ranking to 0.
Authentication: requires the value of PLACES_ADMIN_AUTH_TOKEN.
Pre-configured service token for service-to-service authentication.
This authentication method is used for internal service calls, such as
the data team's ranking updates. The token value must match either the
DATA_TEAM_AUTH_TOKEN or the PLACES_ADMIN_AUTH_TOKEN environment
variable configured on the server.
To authenticate:
Include in requests: Authorization: Bearer <service-token> or Authorization: <service-token>
World id, which is the world name lowercased (for example gather.dcl.eth)
World excluded from the automated ranking
A Decentraland World - privately owned virtual space
Unique world identifier
World name
World description
World thumbnail URL
Owner's Ethereum address
Coordinate placeholders (worlds don't use Genesis City coordinates)
Base coordinate placeholder
^-?\d{1,3},-?\d{1,3}$Content rating
External ranking value for custom ordering
0True if this world is highlighted/featured by administrators
True if the automated discovery score must not rank this entity. It stays browsable
and keeps appearing in listings; only the scheduled scoring job is refused, with a
403 on the ranking endpoint. Distinct from highlighted, which moves where the
entity shows, and from hidden and disabled, which take it out of browse and out
of the catalogue. Survives a redeployment.
falseExample: falseTrue if world opted out of listing
Current users in the world
Visits in last 30 days
The creator's wallet address
^0x[a-fA-F0-9]{40}$SDK/runtime version (e.g., "7" for SDK7)
7List of wallet addresses currently connected to this world.
Only included when with_connected_users=true query parameter is set.
Unauthorized - Missing or invalid authentication token
Resource not found - Place/world doesn't exist or is disabled
PUT /api/worlds/{world_id}/ranking-exclusion HTTP/1.1
Host: places.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"title": "text",
"description": "text",
"image": "https://example.com",
"owner": "text",
"positions": [
"text"
],
"base_position": "text",
"contact_name": "text",
"contact_email": "text",
"content_rating": "text",
"likes": 1,
"dislikes": 1,
"like_score": 1,
"like_rate": 1,
"ranking": 0,
"highlighted": true,
"exclude_from_ranking": false,
"favorites": 1,
"disabled": true,
"disabled_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"deployed_at": "2026-01-01T00:00:00.000Z",
"user_like": true,
"user_dislike": true,
"user_favorite": true,
"user_count": 1,
"user_visits": 1,
"creator_address": "text",
"sdk": "7",
"connected_addresses": [
"text"
]
}Clear the exclusion so the automated discovery score may rank this world again.
Authentication: requires the value of PLACES_ADMIN_AUTH_TOKEN.
Pre-configured service token for service-to-service authentication.
This authentication method is used for internal service calls, such as
the data team's ranking updates. The token value must match either the
DATA_TEAM_AUTH_TOKEN or the PLACES_ADMIN_AUTH_TOKEN environment
variable configured on the server.
To authenticate:
Include in requests: Authorization: Bearer <service-token> or Authorization: <service-token>
World id, which is the world name lowercased (for example gather.dcl.eth)
World returned to the automated ranking
A Decentraland World - privately owned virtual space
Unique world identifier
World name
World description
World thumbnail URL
Owner's Ethereum address
Coordinate placeholders (worlds don't use Genesis City coordinates)
Base coordinate placeholder
^-?\d{1,3},-?\d{1,3}$Content rating
External ranking value for custom ordering
0True if this world is highlighted/featured by administrators
True if the automated discovery score must not rank this entity. It stays browsable
and keeps appearing in listings; only the scheduled scoring job is refused, with a
403 on the ranking endpoint. Distinct from highlighted, which moves where the
entity shows, and from hidden and disabled, which take it out of browse and out
of the catalogue. Survives a redeployment.
falseExample: falseTrue if world opted out of listing
Current users in the world
Visits in last 30 days
The creator's wallet address
^0x[a-fA-F0-9]{40}$SDK/runtime version (e.g., "7" for SDK7)
7List of wallet addresses currently connected to this world.
Only included when with_connected_users=true query parameter is set.
Unauthorized - Missing or invalid authentication token
Resource not found - Place/world doesn't exist or is disabled
DELETE /api/worlds/{world_id}/ranking-exclusion HTTP/1.1
Host: places.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"title": "text",
"description": "text",
"image": "https://example.com",
"owner": "text",
"positions": [
"text"
],
"base_position": "text",
"contact_name": "text",
"contact_email": "text",
"content_rating": "text",
"likes": 1,
"dislikes": 1,
"like_score": 1,
"like_rate": 1,
"ranking": 0,
"highlighted": true,
"exclude_from_ranking": false,
"favorites": 1,
"disabled": true,
"disabled_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"deployed_at": "2026-01-01T00:00:00.000Z",
"user_like": true,
"user_dislike": true,
"user_favorite": true,
"user_count": 1,
"user_visits": 1,
"creator_address": "text",
"sdk": "7",
"connected_addresses": [
"text"
]
}Retrieve a simple list of all registered world names.
Use Cases:
Autocomplete for world search
Validation of world name existence
Browse all available worlds
Performance: Lightweight endpoint, returns only names as strings.
World names retrieved successfully
List of world names
Bad request - Invalid parameters or malformed request
Internal server error - Something went wrong on the server
GET /api/world_names HTTP/1.1
Host: places.decentraland.org
Accept: */*
{
"ok": true,
"data": [
"art-gallery-world",
"concert-venue",
"gaming-arena"
]
}Last updated