Activity reference — Talqen Docs

Availablescope: activity:write

Start shift

POST/v1/activity/shifts/start

Starts or resumes an activity shift for a linked Roblox staff member. Universe must be allowed for the application.

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer <TALQEN_API_KEY>
Idempotency-Key	string	Yes	Unique key for this start attempt.
Content-Type	application/json	Yes	JSON request body.

Body

Name	Type	Required	Description
robloxUserId	string \| number	Yes	Roblox user ID (coerced to string).
universeId	string \| number	Yes	Roblox universe ID; must be in allowed_roblox_universe_ids.
placeId	string \| number	Yes	Roblox place ID.
serverId	string	Yes	Server identifier (1–128 chars). Typically game.JobId.
startedAt	ISO datetime	No	Optional start timestamp. Server clock applies when omitted.

Success responsejson

{
  "data": {
    "shift": {
      "id": "...",
      "status": "active",
      "startedAt": "...",
      "lastHeartbeatAt": "..."
    },
    "existing": true
  }
}

existing may be true when this application already has an active shift for the staff member.
Empty allowed universe list denies all universes.
Unknown staff mapping returns 404.

Availablescope: activity:write

Heartbeat shift

POST/v1/activity/shifts/{shiftId}/heartbeat

Records a heartbeat for an active shift owned by this credential.

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer <TALQEN_API_KEY>
Idempotency-Key	string	Yes	Unique key for this heartbeat attempt.
Content-Type	application/json	No	Required when sending a JSON body.

Path parameters

Name	Type	Required	Description
shiftId	string	Yes	Shift ID returned from start.

Body

Name	Type	Required	Description
recordedAt	ISO datetime	No	Optional heartbeat timestamp.
serverId	string	No	If provided, must match the shift server.

Success responsejson

{
  "data": {
    "shift": {
      "id": "...",
      "status": "active",
      "lastHeartbeatAt": "..."
    }
  }
}

Availablescope: activity:write

Stop shift

POST/v1/activity/shifts/{shiftId}/stop

Stops an active shift and returns duration metrics.

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer <TALQEN_API_KEY>
Idempotency-Key	string	Yes	Unique key for this stop attempt.
Content-Type	application/json	No	Required when sending a JSON body.

Path parameters

Name	Type	Required	Description
shiftId	string	Yes	Shift ID returned from start.

Body

Name	Type	Required	Description
endedAt	ISO datetime	No	Optional end timestamp.
reason	manual \| player_left \| server_shutdown	No	Defaults to manual.

Success responsejson

{
  "data": {
    "shift": {
      "id": "...",
      "status": "completed",
      "startedAt": "...",
      "endedAt": "...",
      "durationSeconds": 0,
      "minutes": 0,
      "endReason": "manual"
    }
  }
}

Availablescope: activity:read

List active shifts

GET/v1/activity/shifts/active

Lists active shifts visible to this credential.

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer <TALQEN_API_KEY>

Query parameters

Name	Type	Required	Description
limit	number	No	Default 50; clamped 1–100.
cursorStartedAt	string	No	Pagination cursor.
cursorId	string	No	Pagination cursor.

Success responsejson

{
  "data": {
    "shifts": [
      {
        "id": "...",
        "status": "active",
        "startedAt": "...",
        "lastHeartbeatAt": "...",
        "elapsedSeconds": 0,
        "universeId": "...",
        "placeId": "...",
        "serverId": "...",
        "staff": {
          "id": "...",
          "displayName": "...",
          "robloxUserId": "..."
        }
      }
    ]
  }
}

Availablescope: activity:read

Get acting staff activity summary

GET/v1/activity/me/summary

Returns minute totals and optional active shift for the acting Discord user.

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer <TALQEN_API_KEY>
X-Discord-Guild-Id	string	Yes	Discord guild ID for the connected integration.
X-Acting-Discord-User-Id	string	Yes	Discord user ID of the staff member to resolve.

Success responsejson

{
  "data": {
    "todayMinutes": 0,
    "currentWeekMinutes": 0,
    "previousWeekMinutes": 0,
    "currentMonthMinutes": 0,
    "weeklyRequiredMinutes": 0,
    "progressPercent": 0,
    "activeShift": null,
    "inactivityEffect": null,
    "timezone": "UTC",
    "currentWeekStart": "...",
    "currentWeekEnd": "...",
    "currentMonthStart": "...",
    "currentMonthEnd": "..."
  }
}

Active shift elapsed time is not rolled into completed minute totals.

Availablescope: activity:read

Staff activity summary by Roblox user

GET/v1/activity/staff/{robloxUserId}/summary

Returns activity aggregates for a staff member identified by Roblox user ID.

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer <TALQEN_API_KEY>

Path parameters

Name	Type	Required	Description
robloxUserId	string	Yes	Roblox user ID.

Query parameters

Name	Type	Required	Description
period	week \| month	No	Period selector, or use start+end for a custom range.
start	ISO string	No	Custom range start.
end	ISO string	No	Custom range end.

Success responsejson

{
  "data": {
    "staff": {
      "id": "...",
      "displayName": "...",
      "robloxUserId": "..."
    },
    "period": {
      "start": "...",
      "end": "...",
      "timezone": "UTC"
    },
    "totalSeconds": 0,
    "totalMinutes": 0,
    "completedShifts": 0,
    "activeShift": null
  }
}

Availablescope: activity:read

Get activity leaderboard

GET/v1/activity/leaderboard

Returns ranked staff activity for a week or month period within the credential workspace.

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer <TALQEN_API_KEY>

Query parameters

Name	Type	Required	Description
period	week \| month	No	Defaults to week when omitted or unrecognized.
start	ISO string	No	Optional custom range start (used with end).
end	ISO string	No	Optional custom range end (used with start).
limit	number	No	Default 25; maximum 100.
cursorTotalSeconds	number	No	Pagination cursor (total seconds).
cursorStaffId	string	No	Pagination cursor (staff id).
departmentId	string	No	Filter by department.
includeInactive	true \| 1	No	Include inactive staff when true or 1.

Success responsejson

{
  "data": {
    "entries": [
      {
        "staffId": "...",
        "displayName": "...",
        "robloxUserId": "...",
        "robloxUsername": "...",
        "totalSeconds": 0,
        "totalMinutes": 0,
        "completedShifts": 0,
        "department": "...",
        "rank": "...",
        "progressPercent": 0,
        "position": 1
      }
    ]
  }
}