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://www.chastitytracker.org

HEADER (Authenticated example)

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

HEADER (Public LINK vote example)

POST /api/v2/games.php HTTP/2
Host: www.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

LINK Vote Cooldown (dom=0)

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: www.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: www.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: www.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: www.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.

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: www.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: www.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.