Use AI to process this moduleCopy prompt

API

Use API docs/ to load and/or update this module and its documents programmatically.

Particracy Legacy's API acts as a universal language middleware between the game's various services (i.e. forum, site, portal, scrapping jobs). While each service maintains its own layout, models, schemas, records and even infrastructure, the API acts as a data management bridge between all of them.

This architecture allows the community to develop mods and features for the game independently, especially as software development becomes more and more accessible with the advent of AI powered coding tools.

Access

Although some GET endpoints are publicly available, all PUT/POST/DELETE and some GET methods require an auth key. To issue one, contact @GreekIdiot (Snizer) or @Zanz on the game's official Discord Server.

Continue reading further to the Authentication & Authorisation section below.

Models

For managing the API's universal models across services, see Models or API model/.

Response Format & Codes

All of the API's responses adhere to the following format:

{
    "status": {
        "code": 200,
        "message": "OK",
        "stamp": "i.e. 24 April 2026 05:10:05PM",
        "v": "i.e. 6.5.1"
    },
    "data": null
}

The data field may be non-existent, null, an object, array, boolean or string, so please make sure you create a utility function that validates the field's type, before you proceed to response handling.

You should call / to verify a 200 OK first response before making your actual calls to the API. Call gateways/ or gateways/{gateway_name}/ to fetch the list of available (gateways,) endpoints and response codes.

Specific response codes will include a reason, based on the method/endpoint.

200 OK
204 No content: specific
400 Bad request: specific
401 Unauthenticated (see below)
403 Unauthorised (see below)
404 Not found: specific
408 Timeout (seconds)
500 Server error => auto-calls API discord/log/
503 Under maintenance: configured via API settings/
507 Storage full: specific

For example:

{
    "status": {
        "code": 403,
        "message": "Unauthorised",
        "stamp": "i.e. 24 April 2026 05:10:05PM",
        "v": "i.e. 6.5.1"
    },
    "data": {
        "reason": "user not manager"
    }
}

Gateways

Continue reading further to view the API's endpoints below.

banana/ (AI related endpoints)
system/
gameplay/
roleplay/

Authentication & Authorisation

System access

To be able to use POST/PUT/DELETE and certain GET methods on the API's various gateways and endpoints, you must include an authorisation key on all of these requests.

401

Management permissions

Certain POST/PUT/DELETE endpoint methods additionally require a handler field with the player's username matching a mod, admin or game master on API community/ (TO-DO switch to API sso/).

These can be identified by the requirement of the handler field in the request body.

403: user not manager

User permissions

Other endpoint methods may further extend permission management in the same manner, by requiring a username to match an active player on API community/ (TO-DO switch to API sso/) who may, or may not be allowed to perform an action, i.e. too inactive to request a cultural protocol change.

403: user not allowed: X

Special token

Special impactful and irreversible actions through certain POST/PUT and all DELETE methods additionally require both a special token handshake and a verification of the user's role as a mod, admin or game master.

These can be identified by the requirement of the token and handler fields in the request body.

Use API token/ to generate tokens.

API