API documentation

Availability

Activity minute tracking routes authenticate with API keys when deployed. Application review routes still require dashboard session authentication.

Overview

Talqen's API connects Roblox experiences, Discord services, and operational systems to Talqen workspaces. Clients authenticate with scoped API credentials created in the developer portal, then call versioned routes under /v1.

Credentials belong to a developer application that is approved for a specific workspace. Talqen does not grant unrestricted platform access through a user profile alone.

Base URLs

Production:

https://api.talqen.net/v1

Staging:

https://api-staging.talqen.net/v1

Gateway metadata (unversioned):

https://api-staging.talqen.net/health
https://api-staging.talqen.net/version
https://api-staging.talqen.net/openapi.json
https://api-staging.talqen.net/docs

You are viewing documentation on a non-production API host.

Authentication

Server integrations authenticate with a workspace-scoped API key using the Bearer scheme. Never place keys in URLs, query strings, or client-visible Roblox assets.

Authorization: Bearer talqen_live_...
Content-Type: application/json
X-Talqen-Workspace-Id: <workspace-uuid>

Key prefixes:

• talqen_test_ — test applications and staging integrations
• talqen_live_ — approved live applications on production

Dashboard users continue to authenticate with Talqen accounts. The developer portal reuses the same identity system to manage applications and credentials.

Initial scopes

Workspace owners approve a subset of requested scopes when connecting a developer application. High-risk capabilities such as application decisions, staff promotion, billing, and workspace administration are not available in the initial scope set.

• applications:read
• staff:read
• permissions:check
• events:write
• activity:write
• activity:read
• activity:manage
• identity:write

Roblox universe restrictions

Each approved developer application may specify one or more allowed Roblox universe IDs in the developer portal. Talqen stores these values with the credential and will validate them for signed Roblox requests — do not trust a universe ID supplied in a request body without checking the credential configuration.

Errors

API routes return JSON error bodies with stable machine-readable codes. Common statuses:

• 401 — missing or invalid authentication
• 403 — authenticated but missing required scope or workspace access
• 404 — resource not found in the current workspace context
• 409 — idempotency conflict on command endpoints
• 422 — valid request shape but business rule rejection
• 429 — rate limited; honor Retry-After when present

Idempotency

Write endpoints for Roblox servers, identity linking, rank sync, events, and activity shifts require an Idempotency-Key header (8–128 characters). Keys are scoped by workspace, developer application, command, and environment. Replaying the same key with the same payload returns the original result; a different payload yields 409 conflict. Records expire after 24 hours.

Roblox ↔ Discord bridge

Game servers authenticate with developer API keys (events:write) to register sessions, mint identity link codes, emit rank/moderation events, and enqueue Discord sync jobs. The Discord bot polls GET /v1/sync/jobs and completes or fails jobs atomically. Link codes are hashed at rest and returned in plaintext only once.

• POST /v1/roblox/servers/register
• POST /v1/roblox/servers/{serverSessionId}/heartbeat
• POST /v1/roblox/servers/{serverSessionId}/stop
• POST /v1/identity/link-codes
• POST /v1/identity/link-codes/consume
• POST /v1/identity/roblox-oauth-verification/start
• GET /v1/identity/roblox/{robloxUserId}
• POST /v1/sync/rank-events
• GET /v1/sync/jobs
• POST /v1/sync/jobs/{jobId}/complete
• POST /v1/sync/jobs/{jobId}/fail
• POST /v1/events
• GET /v1/staff
• GET /v1/staff/{staffId}
• GET /v1/staff/by-roblox/{robloxUserId}
• GET /v1/staff/by-discord/{discordUserId}
• GET /v1/activity/shifts
• GET /v1/activity/shifts/{shiftId}

Minute tracking from Roblox

• Enable HTTP Requests in Roblox Game Settings.
• Run all Talqen requests from ServerScriptService.
• Never send API keys to LocalScripts or replicate them to clients.
• Use talqen_test_ keys against api-staging.talqen.net.
• Use talqen_live_ keys against api.talqen.net after deployment.
• Only approved universe IDs are accepted for shift start.
• Send heartbeats every few minutes; expiry handles disconnects.
• Stop shifts on manual clock-out, PlayerRemoving, and attempt on shutdown.

Placeholders below — verify hostnames before connecting production game servers.

-- Minute tracking from Roblox (Luau)
-- Run from ServerScriptService only. Enable HTTP Requests in Game Settings.
-- Use test keys against api-staging.talqen.net until production endpoints are deployed.

local HttpService = game:GetService("HttpService")
local Players = game:GetService("Players")

local API_BASE = "https://api-staging.talqen.net/v1" -- test/staging
local API_KEY = "talqen_test_REPLACE_ME" -- ServerStorage only, never LocalScripts

local UNIVERSE_ID = "987654321"
local PLACE_ID = tostring(game.PlaceId)

local function talqenRequest(method, path, body, idempotencyKey)
  local headers = {
    ["Authorization"] = "Bearer " .. API_KEY,
    ["Content-Type"] = "application/json",
  }
  if idempotencyKey then
    headers["Idempotency-Key"] = idempotencyKey
  end

  local response = HttpService:RequestAsync({
    Url = API_BASE .. path,
    Method = method,
    Headers = headers,
    Body = body and HttpService:JSONEncode(body) or nil,
  })

  if not response.Success then
    warn("Talqen API error", response.StatusCode, response.Headers["x-request-id"], response.Body)
  end

  return response
end

local function startShift(player)
  local response = talqenRequest("POST", "/activity/shifts/start", {
    robloxUserId = tostring(player.UserId),
    universeId = UNIVERSE_ID,
    placeId = PLACE_ID,
    serverId = game.JobId,
  }, "start-" .. player.UserId .. "-" .. os.time())

  if response.Success then
    local payload = HttpService:JSONDecode(response.Body)
    return payload.data.shift.id
  end
end

local function heartbeatShift(shiftId)
  talqenRequest("POST", "/activity/shifts/" .. shiftId .. "/heartbeat", {
    serverId = game.JobId,
  }, "heartbeat-" .. shiftId .. "-" .. os.time())
end

local function stopShift(shiftId, reason)
  talqenRequest("POST", "/activity/shifts/" .. shiftId .. "/stop", {
    reason = reason or "manual",
  }, "stop-" .. shiftId)
end

-- Heartbeat loop every 3 minutes
task.spawn(function()
  while true do
    task.wait(180)
    for _, shiftId in pairs(activeShifts) do
      heartbeatShift(shiftId)
    end
  end
end)

Players.PlayerRemoving:Connect(function(player)
  local shiftId = activeShifts[player.UserId]
  if shiftId then
    stopShift(shiftId, "player_left")
  end
end)

game:BindToClose(function()
  for userId, shiftId in pairs(activeShifts) do
    stopShift(shiftId, "server_shutdown")
  end
end)

Roblox Luau guide

This example shows the intended request shape. POST /v1/events is not yet available for API-key clients.

-- Planned Talqen API pattern for Roblox (Luau)
-- Event ingestion is not yet generally available on /v1/events.
local HttpService = game:GetService("HttpService")

local API_BASE = "https://api.talqen.net/v1"
local API_KEY = "talqen_live_REPLACE_ME" -- store in ServerStorage, never in ReplicatedStorage

local function postEvent(payload)
  local body = HttpService:JSONEncode(payload)
  local response = HttpService:RequestAsync({
    Url = API_BASE .. "/events",
    Method = "POST",
    Headers = {
      ["Authorization"] = "Bearer " .. API_KEY,
      ["Content-Type"] = "application/json",
      ["X-Talqen-Workspace-Id"] = payload.workspace_id,
    },
    Body = body,
  })

  if not response.Success then
    warn("Talqen API error", response.StatusCode, response.Body)
  end

  return response
end

return {
  postEvent = postEvent,
}

OpenAPI

The machine-readable OpenAPI 3.1 specification is published at /openapi.json. Use it to generate clients or inspect currently implemented routes.