GameCP API

Every page of the GameCP is drawn from a JSON API served by the same webserver binary, under /api/. Anything the panel does, a script can do by calling the same endpoints: post news from a build pipeline, pull the leaderboard into a Discord bot, or watch player counts from a monitoring system.

This page covers the RF Online versions, DragonSoul and World of Kung Fu, which share one control panel. The Gate to Heavens webservers have their own panel and are covered in Gate to Heavens at the end.

This API is not the OSO API. That one is oldschoolops.com's, uses API keys and lives under /api/v1/. This one runs on your own server and signs in with your game account.

Conventions

• Base URL is wherever your GameCP answers, such as https://play.example.com.
• Requests with a body send JSON with Content-Type: application/json.
• Responses are JSON, except /healthz, the downloads and the website's own pages.
• Timestamps are RFC 3339 in UTC unless a field says otherwise. Rate events and the live history use Unix seconds, and say so.
• Field names are camelCase and are the ones the panel itself reads.

The API is the panel's own backend, not a separately versioned product. Endpoints and fields change between releases as the panel does, and the changelog for each release names the ones that moved. Pin a script to the server version it was written against.

Signing In

There are no API keys on a game server. A script signs in the way the browser does and keeps the session cookie.

curl -c cookies.txt -H "Content-Type: application/json" \
     -d '{"email": "[email protected]", "password": "..."}' \
     https://play.example.com/api/auth/login

curl -b cookies.txt https://play.example.com/api/admin/overview

The cookie is named after the game, such as rf2232_session, ds_session or wokf_session, so one browser can be signed in to several servers on the same domain at once. It is HttpOnly, SameSite=Lax, and Secure when the request arrived over HTTPS or through a proxy that sent X-Forwarded-Proto: https. Set COOKIE_DOMAIN under [webserver] in settings.cfg to share the cookie across subdomains; it is applied only when the request's host is that domain or under it.

A session lasts 24 hours from sign-in and is not extended by use. Sessions are held in memory, so restarting the webserver signs everyone out. Banning an account or setting its password from the panel ends its sessions at once.

Every staff endpoint reads your access level from the accounts database on each request. A grant taken away takes effect on the next call, not at the next sign-in.

Signing in through oldschoolops.com

On a server with OSO_SERVER_KEY set under [oso], accounts belong to oldschoolops.com: sign in with your oldschoolops.com email and password, and registration, name changes and password changes answer 403 with a pointer to the site. Everything else on this page works the same. Signing in with oldschoolops.com covers turning it on.

Errors

A refusal written by the panel is JSON with an error sentence, written to be shown to a person:

{"error": "that name is already taken"}

The game database, the live map's HTTP fallback and the character profiles answer with a message field instead, as do requests to a path or method that does not exist.

A feature this server does not have is not an error. The game database, live map, profiles, PvP feed, rate events, rewards and character editor answer 200 with "available": false and a reason, so a script can tell "this server does not do that" from "something went wrong".

Server controls behave the same way. A control request answers 200 with ok and a message whether or not the game server carried it out, because the panel's request succeeded; read ok.

Limits

Limits are counted per address. Behind a reverse proxy on the same machine or private network, the panel reads the client address from X-Forwarded-For, so the proxy must set it.

Accounts

Sign-in, registration and me all answer with the same account document:

{"email": "[email protected]", "name": "Kestrel", "accountId": 17, "gmLevel": 3, "gmLevelName": "Administrator"}

me adds emailVerified. gmLevel is there so a page knows what to draw; the server checks the level again on every staff request, so changing it in a client changes nothing.

A wrong password and an unknown email both answer 401 with the same message. A banned account answers 403 with "banned": true, the reason and bannedAt, and only once the password was right. Accounts are shared by every game on the server, so the same email and password work in the launcher and on every game's GameCP.

Support Tickets

The player's side. Each one answers only for the signed-in account's own tickets on this game.

{
  "id": 12,
  "subject": "Lost my sword",
  "character": "Kestrel",
  "status": "open",
  "createdAt": "2026-10-27T18:02:11Z",
  "lastReplyAt": "2026-10-27T18:02:11Z",
  "replies": 0,
  "waitingOnStaff": true,
  "messages": [
    {"id": 31, "author": "Kestrel", "fromStaff": false, "body": "It vanished after a relog.", "createdAt": "2026-10-27T18:02:11Z"}
  ]
}

status is one of open, response_required, answered, escalated or closed. Staff notes marked internal never appear here.

Public Data

No sign-in needed. These are what the public half of the website is drawn from, and each one sets a short Cache-Control so a busy page does not reach the database on every view.

/api/status answers whether the game is up. /healthz answers whether the website is up. Point an uptime monitor at the one you mean.

{"online": true, "players": 12, "maxPlayers": 500, "monsters": 8421, "uptimeSeconds": 86400,
 "accounts": 311, "characters": 402, "races": {"Bellato": 140, "Cora": 131, "Accretia": 131}}

{"entries": [{"rank": 1, "name": "Kestrel", "level": 55, "race": "Cora", "classCode": "CWB1",
              "className": "Warlock", "contribution": 1834.5, "online": true}],
 "race": "Cora", "ranked": true, "onlineKnown": true}

On a version that ranks by contribution, ranked is true and race filters the list. Elsewhere the list is by level and race returns nothing. online means something only when onlineKnown is true.

The live map

The map page holds a websocket at /api/world/ws and is pushed a new frame about ten times a second while anyone is watching. After connecting, choose a map:

{"action": "watch", "map": 7}

"map": null watches the whole world. Each frame looks like this:

{"type": "world", "map": 7, "state": "live", "total": 214, "truncated": false,
 "entities": [{"kind": 0, "name": "Kestrel", "race": 2, "map": 7, "x": 1032.5, "y": -12.0, "z": 877.25}]}

state is live, pending (the map has not been read yet), offline or disabled, with a message for the last two. kind is 0 player, 1 monster, 2 NPC, 3 animus, 4 object, 5 staff, 6 boss. Which kinds are sent is set under Admin -> Site. The socket accepts connections only from a page on the same host name.

A program that cannot hold a socket can poll GET /api/world?map=7 for the same frame. Polling keeps that map being read for 45 seconds after the last request.

When the live map is set to staff only, a visitor who is not staff gets exactly the answer they would get if it were switched off.

The Control Panel

Everything under /api/admin/. Each endpoint has a minimum access level, from Staff Accounts:

Game Master has no endpoint of its own here: a Game Master can use what a Moderator can.

Anything that acts on another account also follows the outrank rule: the target must hold a lower level than you on this game, and it may not be you. A Moderator can ban a player but not another Moderator. This answers 403.

Overview and live operations

POST /api/admin/control takes op, and text or seconds where the operation needs them:

curl -b cookies.txt -H "Content-Type: application/json" \
     -d '{"op": "restart", "seconds": 300}' \
     https://play.example.com/api/admin/control

{"ok": true, "message": "restart in 5 minutes"}

The panel talks to the game server over a loopback connection authenticated by the admin-token file the game server writes beside settings.cfg. If the two programs read different folders the token will not match and every control answers ok: false naming the file it expected.

Accounts and staff

Accounts are shared by every game on the server, so a ban is too. Banning an account on one game's GameCP stops it signing in to all of them.

curl -b cookies.txt -H "Content-Type: application/json" \
     -d '{"reason": "gold spam in global chat"}' \
     https://play.example.com/api/admin/accounts/42/ban

{"accountId": 42, "ban": {"banned": true, "reason": "gold spam in global chat", "at": "2026-10-28T12:00:00Z", "byId": 7, "byName": "Kestrel"}}

A kick answers 200 with ok: false when the player is not online.

Settings

The setting keys differ between games and are the key fields GET returns. A server with no editable settings answers {"groups": []}.

Rate events and rewards

A rate event multiplies the named rates between two times, then puts back any rate nobody has changed in the meantime. Players are told in game when it starts.

{"name": "Double XP weekend", "keys": ["..."], "multiplier": 2, "startsAt": 1793000000, "endsAt": 1793172800}

keys are from the rates list GET returns. multiplier is 0.1 to 100, times are Unix seconds, an event lasts at most 31 days, and two events may not touch the same rate at once. status is scheduled, active, done, cancelled, or missed for an event the server was not running for.

A reward is mailed to one character or to everyone online:

{"to": "Bob", "title": "Sorry!", "body": "For the downtime", "item": "...", "count": 5, "gold": 0}

Set "allOnline": true instead of to for everyone online. title is up to 20 characters and body up to 200; send an item code, gold, or both. The answer says how many characters it reached.

Credits

Every movement is a ledger row with the reason and who made it.

News

An article takes title (up to 200 characters), body in markdown (up to 256 KiB), categorySlug or categoryId, and optionally slug, author and date. Set "published": true to publish now, or publishedAt to publish with a given date; "publishedAt": "" takes it back to a draft. There is no permanent delete.

curl -b cookies.txt -H "Content-Type: application/json" \
     -d '{"title": "Server maintenance tonight", "categorySlug": "news", "body": "Down from 02:00 for an hour.", "published": true}' \
     https://play.example.com/api/admin/news/articles

Support tickets, staff side

Every ticket endpoint is open to Moderator and up, with no second level inside it: everyone on staff can read, reply, assign and close.

Game data

On the RF Online versions with a Game Data Editor. Reading is Administrator; anything that saves, and the check that rehearses a save, is Super Administrator.

A save names the version it was made against, so two people editing at once cannot overwrite each other:

{
  "baseVersion": "<version from GET /api/admin/gamedata>",
  "edits": [{"table": "...", "key": {"rid": 1317, "seq": -1}, "column": "...", "value": "120"}],
  "rows": [{"table": "...", "op": "append", "values": {"...": "..."}}],
  "allowRenumber": false
}

edits changes cells and rows adds or removes rows (append, insert, delete). Inserting or deleting moves every row after it, so it needs "allowRenumber": true. Every cell is checked before anything is written: if one is refused, the answer is 422 with a violations list and nothing is saved. If someone else saved since your baseVersion, the answer is 409; read the data again and redo the change.

A successful save answers with the new version, which tables changed, whether it is live, and any client files it rewrote. Those are copied into the client/ folder the launcher patches from.

Character editor

Every character editor endpoint is Super Administrator, reading included, on the versions that have it.

A save carries baseVersion from the character you loaded, a reason, and fields and/or items:

{
  "baseVersion": "<version from the character>",
  "reason": "restore lost sword",
  "fields": [{"name": "level", "value": "50"}],
  "items": [{"op": "create", "item": {"container": 0, "slot": 3, "tableCode": 6, "itemIndex": 1317}}]
}

A character cannot be edited while their account is in the game: the save answers 409 with the character's presence. When the game server cannot be asked, the save also answers 409 unless you add "acknowledgeOffline": true to confirm the player is offline. Every save is recorded in the history with who made it and the reason.

Downloads

Served when the server has a client/ folder, for the launcher to patch from. Client updates covers building the manifest.

Which Games Have What

Accounts, support tickets, news, status, the leaderboard, website settings, staff, the account tools, credits, and reload, announce and shutdown are on every game below. The rest depends on the version:

GET /api/brand reports the public features of the server you are talking to, and every feature endpoint answers "available": false where it is missing, so a script does not need this table to behave.

Gate to Heavens

Gate to Heavens and Gate to Heavens Classic run their own GameCP. It signs in the same way and answers errors the same way, but its paths and fields differ. Everything above that this section does not mention is not on a Gate to Heavens server. The live map and the server controls are among the endpoints it does not have.

The session cookie is gth_session on Gate to Heavens and gth_classic_session on Gate to Heavens Classic. A staff endpoint called below its level answers 404, not 403.

Accounts and characters

The launcher and game client sign in through /api/servers, /api/auth/entry-token and /api/auth/remember. Those belong to the client and are not for scripts.

Public data

Gate to Heavens also tracks every item by its unique id:

Support tickets

The same as above, at /api/tickets instead of /api/support/tickets. The staff side is at /api/admin/tickets as above, without the account filter.

The control panel

On Gate to Heavens only, an Administrator can also read GET /api/admin/items/{uid}/history and GET /api/admin/players/{name}/items, the item trail for one item or one character.