2b2tAtlas Public API

Build Minecraft mods, map overlays, Discord bots, history tools, waypoint exporters, and research projects with the public 2b2tAtlas data API.

This is a documentation and examples repository. It does not contain the private Atlas application, collector, credentials, moderation tools, or server infrastructure.

Start here

• API base: https://api.blackportal.cloud
• Interactive Atlas: https://2b2tatlas.com
• Live OpenAPI contract: /openapi/v1.json
• MCP endpoint: https://api.blackportal.cloud/mcp
• Official MCP Registry name: io.github.bobymicjohn/2b2t-atlas
• Authentication: none for the public GET routes documented here
• Format: JSON over HTTPS; public reads allow browser CORS

// Find a location
var locations = await http.GetFromJsonAsync<List<Location>>("api/locations");
var mu = locations!.First(x => x.Name.Equals("Mu Megabase", StringComparison.OrdinalIgnoreCase));

// Find bases by group
var groups = await http.GetFromJsonAsync<List<Group>>("api/groups");
var group = groups!.First(x => x.Name.Contains("DonFuer", StringComparison.OrdinalIgnoreCase));
var groupWithBuilds = await http.GetFromJsonAsync<Group>($"api/groups/{group.Id}");

// Query Archive warps for a location
var warps = await http.GetFromJsonAsync<List<Warp>>($"api/warps?locationId={mu.Rowid}&limit=100");

// Follow an eligible warp's worldDownloadMetadataUrl or worldDownloadUrl.
// These are bounded historical Java saves, not complete copies of 2b2t.

// Find locations with WDL-derived map renders
var renders = await http.GetFromJsonAsync<List<Render>>("api/renders?limit=1000");
var renderedLocationIds = renders!.Select(x => x.LocationId).Distinct().ToHashSet();
var threeDimensional = renders.Where(x => x.BlueMapUrl is not null).ToList();

// Query public, reviewed highways and canals
var highways = await http.GetFromJsonAsync<List<Highway>>("api/highways");

The complete, runnable version is in examples/csharp. Dependency-free JavaScript, Python, and a Fabric-oriented Java pattern are included too.

Connect an AI assistant with MCP

2b2tAtlas exposes a public, stateless, read-only Model Context Protocol server. MCP clients can search and traverse the Atlas knowledge graph without downloading the entire catalog or teaching a model every REST relationship.

{
  "mcpServers": {
    "2b2t-atlas": {
      "type": "http",
      "url": "https://api.blackportal.cloud/mcp"
    }
  }
}

The server offers 15 bounded tools for locations, nearby and historical searches, groups and their builds, highways, Archive warps, render provenance, WDL metadata, preserved builds, and dataset statistics. It also exposes stable resources such as 2b2tatlas://location/{id}. See the complete MCP client and tool guide.

The canonical discovery record is published as io.github.bobymicjohn/2b2t-atlas in the official MCP Registry. Its checked-in server.json and OIDC publishing workflow make the remote endpoint independently discoverable and every registry release reproducible.

MCP is an agent interface over the same reviewed Atlas records, not a second AI-generated database. It returns metadata and public HTTPS links rather than putting WDL ZIPs or render images into model context.

All runnable examples default to production. Set ATLAS_API_BASE_URL to point them at a mock or development server; the repository's CI uses this seam to test every example without generating bursts against the public service.

What can I build?

See 2b2t-specific project ideas for more—including safe client-thread patterns, route overlays, pilgrimage lists, historical diffing, and source-aware research tools.

Projects using 2b2tAtlas

• XaeroTools is an open-source browser, merger, backup, and live-sharing toolkit for Xaero's World Map and XaeroPlus data. Its optional 2b2tAtlas overlay loads community-documented locations with Atlas source links, and it can mirror Atlas map imagery for local use.

Built something with the API? Open an integration showcase so other players and tool authors can find it.

Public endpoints

The API reference explains filters, paging, dimensions, stable links, errors, and caching. See the BlueMap 3D guide before embedding historical 3D viewers. The live OpenAPI document is the machine-readable source of truth.

2b2t-aware client guidance

1. Fetch in a background thread. Never block Minecraft's render or client tick thread on HTTP.
2. Cache responses. Location/group/highway reads are cacheable for at least 60 seconds; a mod should usually cache much longer or keep an offline snapshot.
3. Follow apiUrl, canonicalUrl, interactiveUrl, locationApiUrl, and similar link fields instead of rebuilding URLs.
4. Treat coordinates as historical public records—not proof that a base is active, intact, safe, or loaded on the live server.
5. When practical, keep sourceUrl, attribution, and evidence fields with redistributed media or historical claims so their history remains traceable.
6. Tolerate additive JSON fields. Public GET contracts are stable, but the catalog continues to grow.

Static and agent-friendly data

For crawlers, archives, bulk research, and language-model tools, 2b2tAtlas also publishes: