Chastity Tracker API v2 Documentation: Sessions

🔐 Authentication

All API requests must be authenticated via HTTPS using a bearer token.

Usage

URL

https://www.chastitytracker.org

HEADER

GET /api/v2/sessions.php HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
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}
}

📌 Endpoint: GET /api/v2/sessions.php (list)

Returns session items for the token owner, with optional filters and pagination.

Query Parameters

• from: YYYY-MM-DD (optional, interpreted in user's timezone)
• to: YYYY-MM-DD (optional, interpreted in user's timezone)
• active: 0/1 (optional)
• public: 0/1 (optional)
• limit: integer (default 50, max 200)
• offset: integer (default 0)

Rules

• gamesis included only for active sessions.
• Filtering by from/to is done using the user's timezone.
• has_history: 0/1whether the session has at least one history record
• has_games_changes: 0/1 whether the session has at least one game setting change record

Example Request

GET /api/v2/sessions.php?from=2026-01-01&to=2026-02-01&active=0&limit=50&offset=0 HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}


Response Example

{
  "ok": true,
  "data": {
    "count": 2,
    "total": 10,
    "limit": 50,
    "offset": 0,
    "items": [
      {
        "id": 123,
        "start": "2026-01-15 10:00:00",
        "end": "2026-01-17 10:00:00",
        "scheduledend": null,
        "active": 0,
        "lockedby": null,
        "notes": null,
        "public": 0,
        "timezonestart": "+01:00",
        "timezoneend": "+01:00",
        "inserted": "2026-01-17 10:12:30",
        "has_history": 1,
        "has_games_changes": 0
      }
    ]
  },
  "meta":{"version":2}
}

📌 Endpoint: GET /api/v2/sessions.php?id=ID (details)

Returns a single session item owned by the token user.

Rules

• games is included only for active sessions.
• Filtering by from/to is done using the user's timezone.

Example Request

GET /api/v2/sessions.php?id=123 HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}


Response Example

{
  "ok": true,
  "data": {
    "id": 123,
    "start": "2026-02-02 09:00:00",
    "end": null,
    "scheduledend": "2026-02-03 09:00:00",
    "active": 1,
    "lockedby": "PartnerNick",
    "notes": null,
    "public": 0,
    "timezonestart": "+01:00",
    "timezoneend": null,
    "inserted": "2026-02-02 08:00:00",
    "has_history": 1,
    "has_games_changes": 0
    "games": {...}
  },
  "meta":{"version":2}
}

📌 Endpoint: POST /api/v2/sessions.php (insert/start)

Create session(s). Requires token with write permission.

JSON Body

• type: manual | live (default: manual)
• public: 0/1 (optional)
• lockedby: string or null (optional)
• notes: string or null (optional)

Manual Session Fields

• startdate: YYYY-MM-DD
• starttime: HH:MM (optional; if missing => 00:00)
• enddate: YYYY-MM-DD
• endtime: HH:MM (optional; if missing => 00:00)

Live Session Fields

• startdate: YYYY-MM-DD (optional; defaults to "now")
• starttime: HH:MM (optional)
• scheduledend: YYYY-MM-DD (optional)
• scheduledendtime: HH:MM (optional)
• maxend: 0/1 (optional; randomizes scheduled end between now and scheduledend)

Games (live only)

Games are inserted only on live sessions. If any game flag is enabled, scheduledend is required.

• dices: enable Dice game
• links: enable Public Link game
• luck: enable Luck game

Games Payload Fields (live only)

Games are created only if at least one of these flags is enabled:

• dices: 0/1 (enable Dice game)
• links: 0/1 (enable Public Link game)
• luck: 0/1 (enable Luck game)

🎲 Dice Game Fields

• dicenumber: integer
• diceunit: MINUTE | HOUR | DAY | MONTH (invalid values default to DAY)
• dicetimewait: integer
• dicetimeunitwait: MINUTE | HOUR | DAY (invalid values default to HOUR)
• diceminmulti: number (float)
• dicemaxmulti: number (float)

🔗 Public Link Game Fields

• linkadd: integer
• linkaddunit: MINUTE | HOUR | DAY | MONTH (invalid values default to DAY)
• linksub: integer
• linksubunit: MINUTE | HOUR | DAY | MONTH (invalid values default to DAY)
• resetvotes: 0/1 (optional; if set, resets votes behavior; stored in DB field used for LINK)
• linkminmulti: number (float)
• linkmaxmulti: number (float)

🍀 Luck Game Fields

• randadd: integer
• randaddunit: MINUTE | HOUR | DAY | MONTH (invalid values default to DAY)
• randsub: integer
• randsubunit: MINUTE | HOUR | DAY | MONTH (invalid values default to DAY)
• randtimewait: integer
• randtimeunitwait: MINUTE | HOUR | DAY (invalid values default to HOUR)
• randminmulti: number (float)
• randmaxmulti: number (float)

Game Penalties (optional)

Penalties are created only if the corresponding game is enabled and its penalty flag is enabled.

🎲 Dice Penalties

• dicespen: 0/1 (enable penalties for Dice)
• mindiceplay: integer (minimum plays required)
• pendicetime: integer (penalty amount)
• pendiceunit: MINUTE | HOUR | DAY | MONTH (invalid values default to DAY)
• diceplaylimit: 0/1 (optional; if omitted/empty => always=1; if set => always=0)

🍀 Luck Penalties

• luckpen: 0/1 (enable penalties for Luck)
• minluckplay: integer (minimum plays required)
• penlucktime: integer (penalty amount)
• penlcukunit: MINUTE | HOUR | DAY | MONTH (invalid values default to DAY)
• luckplaylimit: 0/1 (optional; if omitted/empty => always=1; if set => always=0)

Games Rules

• scheduledend is required when enabling any game (dices, links, luck).
• For each game: minmultiplier must be ≤ maxmultiplier.
• If at least one game is created, the API also creates a histories row with type=START and schedule=scheduledend.

Rules

• A user can have only one active session. If already active => 409.
• Sessions cannot overlap existing sessions (overlap check in UTC).
• Manual sessions must be at least 1 hour long.
• Dates cannot be in the future and cannot be too far in the past.
• If any game is enabled, scheduledend is required.

Example Request (manual)

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

{
  "type":"manual",
  "startdate":"2026-02-01",
  "starttime":"09:00",
  "enddate":"2026-02-03",
  "endtime":"09:00",
  "public":0
}

Example Request (live without games)

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

{
  "type":"live",
  "scheduledend":"2026-02-10",
  "scheduledendtime":"09:00",
  "public":0
}

Example Request (live + dice game)

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

{
  "type":"live",
  "scheduledend":"2026-02-10",
  "scheduledendtime":"09:00",
  "maxend":1,
  "dices":1,
  "dicenumber":2,
  "diceunit":"DAY",
  "dicetimewait":6,
  "dicetimeunitwait":"HOUR",
  "diceminmulti":1.0,
  "dicemaxmulti":2.0
}

Response Example

{
  "ok": true,
  "data": {
    "status":"Session started successfully",
    "id": 999,
    "games": true
  },
  "meta":{"version":2}
}

Status Codes

• 201 Created — Inserted
• 400 Bad Request — Validation error
• 401 Unauthorized — Missing/invalid token
• 403 Forbidden — Missing write permission
• 409 Conflict — Active session exists / overlap
• 500 Internal Server Error — Server error

📌 Endpoint: PATCH /api/v2/sessions.php?id=ID (update/stop)

Update session fields or stop a live session. Requires token with write permission. Only provided fields are updated.

Updatable Fields

• public, lockedby, notes
• scheduledend, scheduledendtime (set scheduledend to null to remove)

Stop Live Session

• endNow: true (stop now)
• OR enddate: YYYY-MM-DD (+ optional endtime)

Rules

• Stopping is allowed only if the session is currently active=1.
• End cannot be in the future and must be at least 1 hour after start.

Example Request (stop now)

PATCH /api/v2/sessions.php?id=999 HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}
Content-Type: application/json

{
  "endNow": true
}

📌 Endpoint: DELETE /api/v2/sessions.php?id=ID (delete)

Delete session by id. Requires token with write permission.

Rules

• Cannot delete an active session. Stop it first.

⚠️ 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-02-02: initial v2 release

To go back to documentation index click here.