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:

• llms.txt
• dataset.json
• locations.jsonl
• groups.jsonl
• media.jsonl
• world-downloads.jsonl
• crawlable world-download catalog
• MCP server guide and remote endpoint at https://api.blackportal.cloud/mcp
• official MCP Registry record under io.github.bobymicjohn/2b2t-atlas
• canonical HTML/JSON-LD pages under /entities/locations/{id}/ and /entities/groups/{id}/

Use the live API for interactive applications and the static feeds for deliberate bulk ingestion. The WDL feed identifies every available ZIP as a partial Java save and links it to its canonical location and render, plus its exact Archive warp when one exists. sourceType and scope distinguish collector-bounded snapshots from verified preserved sources behind older/community renders. See LLM and bulk-data guidance.

Credit the data

Use Atlas data however you want. No Atlas credit or permission is required. If Atlas data is visible or materially powers your project, this simple optional credit helps players find the historical source:

Data provided by [2b2tAtlas](https://2b2tatlas.com).

For a mod About screen, README badge, website footer, or machine-readable notice, see ATTRIBUTION.md. Original-source fields returned with attachments and evidence are kept so downstream projects can credit and verify them too.

Repository map

examples/
  csharp/       complete .NET console example
  fabric/       async Java/Fabric integration pattern
  javascript/   dependency-free Node example
  python/       dependency-free Python example
  requests.http copy-ready REST Client requests
docs/
  API-REFERENCE.md
  BLUEMAP-3D.md
  MCP.md
  COORDINATES-AND-RENDERS.md
  2B2T-IDEAS.md

Contributing and integrations

• Open an integration showcase when your tool uses the API.
• Report unclear or stale documentation through the issue templates.
• Add examples in another language or a small integration recipe through a pull request.
• Ask for a new public read projection by describing the player/developer use case; never post credentials or non-public coordinates.

Read CONTRIBUTING.md before submitting code. Questions and project demos are welcome in GitHub Discussions.

Stability and affiliation

Public read models may gain fields as the historical graph grows. Clients should ignore unknown JSON properties and use nullable handling for incomplete historical metadata. Write/admin endpoints are intentionally outside this repository.

2b2tAtlas is a community historical project and is not affiliated with Mojang Studios, Microsoft, or the operators of 2b2t. Minecraft names and assets belong to their respective owners.

Design references

The repository's task-first examples and integration guidance borrow useful documentation patterns from HypixelDev/PublicAPI, GTNewHorizons/Navigator, and odds-api/odds-api, adapted to the very different needs of a historical 2b2t map and entity graph.

License

Repository-authored examples and documentation are released under the Unlicense: copy, modify, publish, commercialize, or remix them for any purpose without permission or required attribution. Atlas likewise places no attribution condition on reuse of its factual API catalog; a link back is simply appreciated. Some records reference third-party media whose original source terms remain separate, as explained in NOTICE.md.