Chastity Tracker API v2 Documentation: Histories

🔐 Authentication

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

Usage

URL

https://www.chastitytracker.org

HEADER

GET /api/v2/histories.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}
}

ℹ️ About Histories

Histories are read-only records generated by the system to track changes during a session (games, penalties, manual adjustments, dom actions).

Field Meaning

• type: START | ADD | SUB
• unit: seconds (integer). Only for ADD/SUB, null for START
• source: DICE | LINK | LUCK | MANUAL | PENALTY | DOM (nullable)
• dom: 0/1 (1 means performed by a dom)
• schedule: UTC datetime target affected by the change
• happened: UTC datetime(3) when the change occurred

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

Returns history items for a specific session (token owner only).

Query Parameters

• session: integer (required)
• type: START | ADD | SUB (optional)
• source: DICE | LINK | LUCK | MANUAL | PENALTY | DOM (optional)
• dom: 0/1 (optional)
• from: UTC datetime (optional) — filter on happened >= from
• to: UTC datetime (optional) — filter on happened <= to
• limit: integer (default 50, max 200)
• cursor: string (optional, cursor pagination)

Sorting

• Always ordered by happened DESC, schedule DESC, source ASC.

Example Request

GET /api/v2/histories.php?session=123&limit=50 HTTP/2
Host: www.chastitytracker.org
Authorization: Bearer {YOUR_API_TOKEN}


Response Example

{
  "ok": true,
  "data": {
    "count": 2,
    "limit": 50,
    "cursor_next": "eyJoYXBwZW5lZCI6IjIwMjYtMDItMDMgMDk6MzA6MDcuMTIzIiwic2NoZWR1bGUiOiIyMDI2LTAyLTEwIDAwOjAwOjAwIiwic291cmNlIjoiRElDRSJ9",
    "has_games_changes": 1,
    "items": [
      {
        "session": 123,
        "type": "START",
        "unit": null,
        "source": null,
        "dom": 0,
        "schedule": "2026-02-10 00:00:00",
        "happened": "2026-02-03 09:30:07.123"
      },
      {
        "session": 123,
        "type": "ADD",
        "unit": 86400,
        "source": "DICE",
        "dom": 0,
        "schedule": "2026-02-11 00:00:00",
        "happened": "2026-02-03 10:02:11.456"
      }
    ]
  },
  "meta":{"version":2}
}

Status Codes

• 200 OK — Returned
• 400 Bad Request — Validation error
• 401 Unauthorized — Missing/invalid token
• 500 Internal Server Error — Server error

⚠️ Notes

• Histories are read-only in v2 (no insert/update/delete).
• unit is expressed in seconds to match the tracker’s existing logic/UI.
• All timestamps are UTC (as stored in database).

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

To go back to documentation index click here.