Chastity Tracker API v2 Documentation: Games (DICE / LUCK / LINK)

🔐 Authentication

Game-play requests may be public or require authentication depending on the mode. Updating game settings always requires authentication via HTTPS bearer token with write permission.

Rules

• DICE: bearer token required.
• LUCK: bearer token required.
• LINK dom=1 (dom play): bearer token required.
• LINK dom=0 (public vote): bearer token not required (optional).
• PATCH game settings: bearer token with write permission required.

Usage

URL

https://chastitytracker.org

HEADER (Authenticated example)

POST /api/v2/games.php HTTP/2
Host: chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

HEADER (Public LINK vote example)

POST /api/v2/games.php HTTP/2
Host: chastitytracker.org
Content-Type: application/json

📦 Response Envelope

All v2 endpoints return a unified JSON envelope.

Success

{
  "ok": true,
  "data": { ... },
  "meta": {"version":2}
}

Error

{
  "ok": false,
  "error": {"code":"...", "message":"..."},
  "meta": {"version":2}
}

ℹ️ About Games

Game actions modify a session’s scheduledend and generate a new entry in histories. Game settings can also be added, updated, or explicitly deleted during an active session. Supported games are: DICE, LUCK, LINK.

Common Output Fields

• session: session id
• dom: 0/1 (1 means performed by a dom)
• operation: ADD | SUB
• seconds: seconds added or subrtracted
• scheduledend_utc: new UTC scheduled end after the operation
• multiplier: random multiplier

Security

• DICE/LUCK are always private and require bearer token.
• LINK can be public (dom=0) if the user enabled the LINK game and shares the token link.

📌 Endpoint: POST /api/v2/games.php

Plays a game action and updates the session schedule.

Request Body (JSON)

{
  "game": "dice" | "luck" | "link",
  "dom": 0 | 1,
  "session": 123,
  "token": "PUBLIC_LINK_TOKEN",
  "type": "add" | "sub" | "rand"
}

Fields

• game: required. Allowed: dice, luck, link.
• dom: required. 0 = owner/public, 1 = dom action.
• session: required for DICE, LUCK, and LINK dom=1. Optional for LINK dom=0 if token is provided (session is resolved by token).
• token: required for LINK dom=0 (public vote). Optional elsewhere.
• type: required for LINK (both dom modes). Allowed: add, sub, rand.

Permission Rules

• DICE/LUCK:
  • dom=0: bearer token user must be the session owner.
  • dom=1: bearer token user must be the dom of the owner (active link required).
• LINK:
  • dom=1: bearer token required, must be dom of the owner.
  • dom=0: public vote, no bearer required. If bearer is present, it is used to identify the voter.

⚠️ Penalty (Immediate)

For LINK dom=0, if the request includes a bearer token belonging to the session owner, the API triggers a penalty immediately:

• penalty = 1
• type is forced to add
• multiplier is forced to maxmultiplier
• history source becomes PENALTY

Successful LINK vote responses include publicmessage: the plain-text message read from the game when the vote is processed, or an empty string if no message is set. Render it as text, not HTML. This field is independent of the hide-settings and statistics options.

LINK Vote Cooldown (dom=0)

When random-only voting is enabled, public voters must send type="rand". Direct add or sub requests are rejected. Verified keyholder actions and owner penalties keep their existing behavior.

When settings are hidden, public responses omit int, unit, time, and multiplier. The resulting seconds and scheduled end remain visible. If public statistics are enabled, linkstats contains votes, added/removed/net seconds, and formatted labels for this session. Owner penalties and keyholder actions are excluded.

Votes are limited according to LINK configuration:

• waitint=0: vote once ever.
• waitint=1: vote again after 24 hours.

Vote Uniqueness

• Logged voter (bearer present): uniqueness is by (token, session, user) only (IP is ignored).
• Anonymous voter (no bearer): uniqueness is by (token, session, ip) where user IS NULL.

Example Requests

1) Public LINK vote (anonymous)

POST /api/v2/games.php HTTP/2
Host: chastitytracker.org
Content-Type: application/json

{
  "game":"link",
  "dom":0,
  "token":"AbCdEf123...",
  "type":"rand"
}

2) Public LINK vote (logged)

POST /api/v2/games.php HTTP/2
Host: chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "game":"link",
  "dom":0,
  "token":"AbCdEf123...",
  "type":"add"
}

3) DICE (owner)

POST /api/v2/games.php HTTP/2
Host: chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "game":"dice",
  "dom":0,
  "session":123
}

4) LUCK (dom)

POST /api/v2/games.php HTTP/2
Host: chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "game":"luck",
  "dom":1,
  "session":123
}

Response Examples

LINK

{
  "ok": true,
  "data": {
    "game":"link",
    "operation":"ADD",
    "multiplier":1.37,
    "time":3600,
    "unit":"hour",
    "int":1,
    "seconds":3600,
    "dom":0,
    "scheduledend_utc":"2026-02-10 00:00:00",
    "session":123,
    "penalty":null
  },
  "meta":{"version":2}
}

DICE

{
  "ok": true,
  "data": {
    "game":"dice",
    "operation":"SUB",
    "time":7200,
    "sum":-3,
    "dices":[6,1,2],
    "dicesops":["","s",""],
    "calc":"+6-1+2",
    "multiplier":1.11,
    "seconds":7200,
    "dom":0,
    "scheduledend_utc":"2026-02-10 00:00:00",
    "session":123
  },
  "meta":{"version":2}
}

LUCK

{
  "ok": true,
  "data": {
    "game":"luck",
    "operation":"ADD",
    "time":86400,
    "int":1,
    "multiplier":1.22,
    "seconds":86400,
    "dom":1,
    "scheduledend_utc":"2026-02-11 00:00:00",
    "session":123
  },
  "meta":{"version":2}
}

Status Codes

• 200 OK — Played successfully
• 400 Bad Request — Validation error (missing fields, cooldown, etc.)
• 401 Unauthorized — Missing/invalid token (where required)
• 403 Forbidden — Permission denied (not owner / not dom)
• 404 Not Found — Link token or session not found
• 405 Method Not Allowed — Not POST
• 500 Internal Server Error — Server error

📌 Endpoint: PATCH /api/v2/games.php?session=ID (update settings)

Adds, updates, or explicitly deletes game settings for an active session. Requires a bearer token with write permission.

Explicit Actions

• session is a required positive session id in the query string.
• dices: 1, links: 1, or luck: 1 adds or updates that game using its complete configuration.
• deletedices: 1, deletelinks: 1, or deleteluck: 1 explicitly deletes that game.
• Omitting a game and its delete field leaves that game unchanged.
• Action fields accept only the JSON numbers 0 and 1. A value of 0 is accepted but performs no action.
• A game cannot be updated and deleted in the same request.

Permission Rules

• The session must exist and be active.
• The active keyholder of the session owner has full update and delete rights.
• The session owner can update settings only when no active keyholder exists. Owner changes must make the session equally or more restrictive (self-hardening).
• Self-hardening allows adding a game, but does not allow disabling an existing game.
• For Dice, the owner cannot reduce the number or time unit, increase the wait between plays, reduce multipliers, or remove/weaken a penalty.
• For Link and Luck, the owner cannot reduce add time, increase subtract time, reduce multipliers, or otherwise make voting/play requirements easier. Luck penalties cannot be removed or weakened.

Dice Configuration

When dices: 1 is supplied, all of these fields are required:

• dicenumber: number of dice (maximum 5).
• diceunit: MINUTE | HOUR | DAY | MONTH.
• dicetime: wait amount between plays.
• dicetimeunit: MINUTE | HOUR | DAY.
• diceminmulti, dicemaxmulti: multiplier range; minimum must not exceed maximum.

If dicepen: 1 is supplied, mindicenum, pendicetime, and pendiceunit are required. pendicelimit and pendicewindow are optional.

Link Configuration

When links: 1 is supplied, all of these fields are required:

• linkadd, linkaddunit: time added by a vote.
• linksub, linksubunit: time subtracted by a vote.
• linkminmulti, linkmaxmulti: multiplier range; minimum must not exceed maximum.
• linkvotes: optional 0/1; 1 allows voting again after 24 hours.
• linkminvotes: optional minimum vote count, within the service limit.
• linkrandomonly: optional 0/1; restrict public voters to Random. Once enabled, a self-managed session cannot disable it.
• linkhidesettings: optional 0/1; hide the configured base times, multipliers, and calculation breakdown.
• linkshowstats: optional 0/1; show aggregate public votes and time changes.
• linkpublicmessage: optional plain text up to 500 Unicode characters; use an empty string to clear it.
• Omitted new preferences retain their saved values during updates. New games default to all switches off and an empty message. The existing owner/keyholder permissions still apply.

Time units accept MINUTE, HOUR, DAY, or MONTH.

Luck Configuration

When luck: 1 is supplied, all of these fields are required:

• luckadd, luckaddunit: possible time addition.
• lucksub, lucksubunit: possible time subtraction.
• lucktime: wait amount between plays.
• lucktimeunit: MINUTE | HOUR | DAY.
• luckminmulti, luckmaxmulti: multiplier range; minimum must not exceed maximum.

If luckpen: 1 is supplied, minlucknum, penlucktime, and penluckunit are required. penlucklimit and penluckwindow are optional.

Example Request: update Dice only

Link and Luck are not mentioned, so they remain unchanged.

PATCH /api/v2/games.php?session=123 HTTP/2
Host: chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "dices":1,
  "dicenumber":3,
  "diceunit":"DAY",
  "dicetime":6,
  "dicetimeunit":"HOUR",
  "diceminmulti":1.0,
  "dicemaxmulti":2.0
}

Example Request: explicitly delete Link

PATCH /api/v2/games.php?session=123 HTTP/2
Host: chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "deletelinks":1
}

Response Example

{
  "ok":true,
  "data":{
    "updated":true,
    "session":123,
    "mode":"keyholder"
  },
  "meta":{"version":2}
}

mode is keyholder for an active keyholder or self_harden for an eligible session owner. updated is false when the request causes no stored change.

Atomicity and Status Codes

• The entire request is transactional. A validation or permission failure rolls back every game and game-change record from that request.
• At least one game must remain active after the request.
• Successful changes are recorded in games_changes.
• 200 OK — Request processed successfully.
• 400 Bad Request — Invalid JSON action/configuration, conflicting actions, self-hardening violation, or deletion of the final game.
• 401 Unauthorized — Missing or invalid bearer token.
• 403 Forbidden — Missing write permission or actor is not allowed to update the session.
• 404 Not Found — Active session not found.
• 405 Method Not Allowed — Unsupported method.
• 500 Internal Server Error — Server error.

⚠️ Notes

• All timestamps returned by this endpoint are UTC.
• The endpoint inserts a row in histories for each game action.
• For LINK dom=0 (public vote): the API records voters and updates games.used/games.lastuse.
• For penalty: voters are not recorded and LINK game counters are not updated.

⚠️ Security Notes

• Tokens must be stored securely by third parties.
• Users can revoke or regenerate tokens at any time.
• Never share a user’s token or sensitive info.

📅 Changelog

• 2026-08-21: added PATCH support for updating and explicitly deleting active-session game settings
• 2026-02-14: initial v2 release

To go back to documentation index click here.