Bridge endpoint

Base: /api/v1

The single endpoint your plugin talks to the panel through: sends the current state and receives waiting actions.

Handler: MinecraftBridgeController

POST /api/v1/minecraft/bridge

Send status & fetch actions

The same thing your plugin does on every poll interval: reports player state, whitelist and the results of previously sent actions, and receives up to 20 waiting actions plus the current live status in return.

Request Body

Field	Type	Required	Description
`version`	string	No	Plugin-Version, z. B. "1.8.0"
`paused`	boolean	No	"true" oder "false"
`game`	string	No	"minecraft" oder "hytale"

Response Example

{
  "actions": [
    {
      "id": 501,
      "action": "fake_death",
      "player": "Steve",
      "params": {},
      "viewer": "ChatterName",
      "label": null,
      "show_title": true
    }
  ],
  "display": {
    "live": true,
    "streamer": "ExampleStreamer",
    "platform": "twitch",
    "url": "https://twitch.tv/examplestreamer",
    "viewers": 128
  }
}

cURL

curl -X POST 'https://your-panel.example/api/v1/minecraft/bridge' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"version":"1.8.0","paused":false,"game":"minecraft"}'

Important to understand: this is the poll the plugin itself makes. To trigger "action X for player Y" on purpose and see the result, use "Send test action" and "Query test status". Here the plugin only reports its status, and the panel independently decides which actions are already waiting (triggered by a channel point redemption, a TikTok gift, an automation, or the test button in the panel itself) and delivers them on the next poll; in demo mode the button therefore only shows an example of what a response with a waiting action looks like (depending on the "game" field). Under "Your server URL" enter the address of the panel your plugin connects to (the same one as in your config.yml), and under "Authorization" your token in the format "Bearer your-token". This call then behaves exactly like a normal poll from your plugin: any waiting actions are marked as "sent" and delivered in this response. Only test live when your server is not currently expecting an action, otherwise your actual plugin will not see that action on its next poll. Note: this test tool always sends the request unencrypted (http) first and does not follow redirects, so against a panel that only accepts encrypted connections (https) you may see just a redirect response here instead of the real data. In that case, use the curl example below.

Internal Behavior

Checks the Bearer token against the registered Minecraft server, stores the last contact time, the reported players/whitelist/items, records the results of previously sent actions, and returns up to 20 waiting actions (marked as "sent", no longer included in a second response afterward).

Possible values for "action" in the returned actions (full table with parameters in the "Actions reference" guide):

commands: runs a list of allowed server commands
drop_hand: drops the item from the main hand
drop_hotbar: randomly drops all hotbar items
throw_item: throws the item from the hand with an upward arc
shuffle_inventory: shuffles the inventory
hotbar_chaos: temporarily switches the hotbar slot at random
pin: fixes the player in place
knockback: knocks the player back
invert_controls: inverts the controls
strip_armor: removes the armor
damage_tool: damages the tool in hand
hot_potato: gives a "hot potato" that explodes once it expires
jail: teleports into a glass cage
cobweb: places cobwebs around the feet
ice_floor: replaces the ground with packed ice
pumpkin_head: puts a pumpkin on the head
sky_launch: launches upward
anvil_rain: drops anvils harmlessly from the sky
harmless_tnt: places TNT without explosion damage
half_health: halves the health
swap_places: swaps position with another player
firework_show: sets off fireworks
set_spawn: sets the respawn point
random_teleport: starts a random high-altitude fall teleport
ground_teleport: ends a high-altitude fall safely on the ground
fake_death: simulates death without real loss

POST /api/v1/minecraft/bridge/test-action

Send test action

Queues an action for your own server, exactly as if a viewer had triggered it. The plugin picks it up on its next poll and executes it. This lets you check the whole chain: the panel accepts it, the plugin picks it up, the game executes it, the result comes back.

Request Body

Field	Type	Required	Description
`action`	string	Yes	Action from the catalog
`player`	string	Yes	Player name (must be online on your server)
`params`	object	No	Parameters as JSON, prefilled when you choose an action
`viewer`	string	No	Displayed viewer name, default "API-Test"

Response Example

{
    "id": 1234,
    "status": "pending",
    "action": "pin",
    "group": "sabotage",
    "player": "Steve",
    "params": {
        "seconds": 10
    },
    "result": null,
    "created_at": "2026-10-14T09:30:00+02:00",
    "sent_at": null,
    "plugin_seen_at": "2026-10-14T09:30:00+02:00"
}

cURL

curl -X POST 'https://your-panel.example/api/v1/minecraft/bridge/test-action' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"action":"pin","player":"Steve","params":{"seconds":10}}'

Demo mode: choose an action (its parameters are prefilled) and a player name, the response shows what the entry would look like; afterwards you can see the result under "Query test status" with the same ID. Own server: enter your panel address and "Bearer your-token" above (the same token as in the plugin configuration), the player must be online. The action is then really executed in the game. Do not call "Send status & fetch actions" at the same time, otherwise you pick up the action instead of your plugin.

Internal Behavior

Checks the token, checks action and player name against the panel action catalog (only actions the plugin executes itself), limits the parameters exactly like real triggers (duration, count, allowed choice values) and creates a queue entry with status "pending". At most 20 test actions per minute.

GET /api/v1/minecraft/bridge/test-action/{id}

Query test status

Shows what became of a test action: "pending" (waiting), "sent" (picked up by the plugin), "done" (executed), "failed" (failed, reason in "result", for example "player_offline" or "no_space") or "expired" (not picked up in time).

Parameters

Name	Type	Required	Description
`id`	integer	Yes	ID from "Send test action"

Response Example

{
    "id": 1234,
    "status": "done",
    "action": "pin",
    "group": "sabotage",
    "player": "Steve",
    "params": {
        "seconds": 10
    },
    "result": null,
    "created_at": "2026-10-14T09:30:00+02:00",
    "sent_at": "2026-10-14T09:30:01+02:00",
    "plugin_seen_at": "2026-10-14T09:30:02+02:00"
}

cURL

curl 'https://your-panel.example/api/v1/minecraft/bridge/test-action/1234' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Enter the ID from "Send test action" under "id". With your own server and token you see the real result from the game here, usually one or two seconds after sending.

Internal Behavior

Only returns entries of your own server. If the plugin does not pick up an entry within 30 seconds or reports no result, it is set to "expired". "plugin_seen_at" shows when the plugin last checked in.