Activity tracking

Shift lifecycle tracking uses three verified write endpoints. Your game owns timing; Talqen owns duration accounting after validated heartbeats and stops.

Status: Available for start, heartbeat, and stop under /v1/activity/shifts.

Lifecycle

POST /v1/activity/shifts/start with Roblox identifiers
Periodically POST /v1/activity/shifts/{shiftId}/heartbeat
POST /v1/activity/shifts/{shiftId}/stop with a reason

Quick curl

Start shiftbash

curl -X POST "https://api-staging.talqen.net/v1/activity/shifts/start" \
  -H "Authorization: Bearer <TALQEN_TEST_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: start-<ROBLOX_USER_ID>-001" \
  -d '{
    "robloxUserId": "<ROBLOX_USER_ID>",
    "universeId": "<UNIVERSE_ID>",
    "placeId": "<PLACE_ID>",
    "serverId": "<SERVER_ID>"
  }'

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"
    }
  }
}

Related reads live in the activity reference.