API · Craft++

Craft++ API

Everything that connects Craft++ to this website: key checking, Pager sign-in, live games, world servers, community services and the craft:// join protocol. All endpoints are JSON over HTTPS on https://craftplusplus.com.

Machine-readable index (/api) Hub integration guide Create a key

Key checking and Pager sign-in

Pager signs in with the player's Craft++ key and password, then keeps the returned session token. Dream Daemon and Dream Seeker validate that token — the same flow BYOND uses for its Pager keys.

POST /api/session
  username=<key>  password=<password>  [twoFactorCode=<code>]
  → 200 { "userId": 2, "username": "yourkey", "sessionToken": "opaque-token" }

POST /api/session/validate
  sessionToken=<opaque-token>
  → 200 { "userId": 2, "username": "yourkey" }   ·   401 when invalid

GET /api/keys/<key>
  → 200 { "key": "yourkey", "gameCount": 1, "games": [ ... ] }   ·   404 when unknown

Passwords are never logged. Failed sign-ins return 401; accounts with 2FA enabled require twoFactorCode. Tokens stay valid until sign-out.

Live games and worlds

Method	Path	Purpose
GET	/api/games	All public listings (filter with `?q=&tag=&status=&sort=`)
GET	/api/games/live	Worlds with players online right now
GET	/api/games/{key.game}	Single listing by Hub path
GET	/api/worlds · /api/worlds/live	World registry (all · live)
GET	/api/status	Service status: games, live games, accounts

The homepage and sidebar consume these endpoints live; every listing also exposes a craft://join?key.game link.

World server lifecycle

Dream Daemon registers its world, heartbeats player counts and marks offline on shutdown, authenticated with the listing's Hub password:

POST /hub/register   hubPath, hubPassword, serverAddress, serverPort, version …
POST /hub/heartbeat  hubPath, players …          (every ~30s)
POST /hub/offline    hubPath                     (clean shutdown)

world
    hub = "yourkey.mygame"
    hub_password = "your-secret-password"

Stale servers stop being joinable after 90 seconds without a heartbeat.

Community services

Method	Path	Purpose
GET	/api/posts	Homepage posts published by the owner
GET · POST	/api/comments/{key.game}	Public comment feed and ratings
GET · POST	/api/groups	Community groups; join/leave and message feeds
GET · POST	/api/presence	Who is online right now
GET · POST	/api/chat	Global community chat
GET · POST	/api/im	Direct messages
GET · POST	/api/files	File transfer between keys (≤ 2 MB)
GET	/api/notifications	Account notifications

Writes require a Hub session (craftpp_hub_session cookie or session token); public reads are anonymous-safe.

Join protocol

Live listings expose a protocol link the client understands:

craft://join?key.game

Dream Seeker resolves the key through the Hub, validates the player session and assigns the canonical key to the mob's key/ckey before Login() runs.