API and addons

Two ways in

Either way, your markers belong to your app: you only see and change your own, and the map's owner can see what you added and remove it. Markers are a Premium feature, so the map's owner needs Premium.

For map owners

Open your world, then API and addons.

• An app or bot: type its name and choose Make an API key. Copy the key (it's shown once) into the app. Revoke stops it at once, and can remove everything it added.
• Addons work as soon as Bedrock Relay is in your world. Switch off Addons may add markers to stop them, and remove any addon's markers from its line.
• Markers from apps show on the Markers page with who added them, and you can edit or delete them like any other.

From a Bedrock addon

Send a script event; Bedrock Relay, in the same world, passes it to BedrockMap. Your addon needs no key and no internet access, so it works on Realms and servers alike.

import { system, world } from '@minecraft/server';

// A death point: one per player, moved each time they die.
world.afterEvents.entityDie.subscribe(({ deadEntity: p }) => {
  if (p.typeId !== 'minecraft:player') return;
  const at = p.location;
  system.sendScriptEvent('bedrockmap:marker', JSON.stringify({
    app: 'DeathPoints',
    ref: `death:${p.name}`,
    name: `${p.name} died here`,
    x: Math.floor(at.x), y: Math.floor(at.y), z: Math.floor(at.z),
    dimension: p.dimension.id,
    type: 'Graves',
  }));
});

// ...and remove it when they get their things back.
system.sendScriptEvent('bedrockmap:remove', JSON.stringify({ app: 'DeathPoints', ref: 'death:Steve' }));

• app: your addon's name (letters, numbers, spaces, - and _, up to 32). Owners see it on their map.
• ref: your own name for the marker, up to 64 characters. Sending the same ref again moves and renames that marker instead of adding another, so you never need to keep ids. Remove markers by ref.
• dimension: minecraft:overworld, minecraft:nether or minecraft:the_end (what dimension.id gives you), or just overworld.
• name up to 80 characters; optional note (shown when clicked) up to 1,000; optional type, one of the map's marker types (icons) by name, like Graves for the owner's own "Graves" icon.
• Markers stay until you remove them. Tidy up: remove a waypoint when it's no longer needed.
• A script event gets no reply. If the owner has switched addons off, or the map is full, the marker simply isn't added.

The API

Send the map owner's key with every request, as Authorization: Bearer bmk_…. Requests and answers are JSON. Base address: https://bedrockmap.net/api/v1.

curl https://bedrockmap.net/api/v1/markers \
  -H "Authorization: Bearer bmk_…" -H "Content-Type: application/json" \
  -d '{"ref":"shop:carrots","name":"The Golden Carrot","dimension":"overworld","x":-130,"z":165,"type":"Shop","note":"Open whenever Mia is on."}'

{
  "marker": {
    "id": 412, "ref": "shop:carrots", "dimension": "overworld",
    "x": -130, "y": null, "z": 165, "name": "The Golden Carrot", "note": "Open whenever Mia is on.",
    "type": "shop", "icon": "shop", "colour": "#e0a030",
    "mapUrl": "https://bedrockmap.net/map/cherry-valley-smp#-130,165,2",
    "createdAt": "2026-10-02T14:00:00.000Z", "updatedAt": "2026-10-02T14:00:00.000Z"
  }
}

Fields: dimension, x, z, optional y, name, optional note, ref, and either type (its icon, by id like shop or custom:31, or by name like Shop or the owner's Graves) or icon (the same ids), and optionally colour (#rrggbb, the pin's colour for a built-in icon).

Errors