---
title: "Register a Team HQ Live Activity"
method: POST
path: "/api/events/{gameId}/live-activity"
tags: ["Events"]
---

# Register a Team HQ Live Activity

`POST /api/events/{gameId}/live-activity`

## Request

- Base URL: `https://app.d-sports.org`
- URL: `https://app.d-sports.org/api/events/{gameId}/live-activity`
- Auth: HTTP bearer

Authenticated. Registers routing for an iOS Lock Screen / Dynamic Island match card, keyed per user + fixture + club. Requires UserSettings.liveScoreUpdates consent (403 FORBIDDEN otherwise). `activityId` is minted server-side (`hq:{gameId}:{teamId}:{userId}`) and returned; the client calls OneSignal.LiveActivities.enter(activityId, pushToken). `pushToken` is an optional hex ActivityKit token stored for that client call. A later POST that omits it does not clear the stored token. The server never sends the token to Apple or OneSignal — Live Activity updates and ends go through OneSignal's live_activities API. Android (#697) writes a `platform:"android"` opt-in row on the same user+fixture+club key (no `pushToken`) and returns `{ registered: true, platform: "android", activityId: <minted>, expiresAt: null }` after the same game/team/consent checks — the row opts the fan into Android Live Update pushes for that fixture+club (they ride ordinary push subscriptions, so no ActivityKit token is stored). A register on an already-live fixture also sends that fan a catch-up push with the current score.

## Path parameters

- `gameId` string, required

## Request body

- object
  - `teamId` string, required: Must be the fixture's homeTeamId or awayTeamId. Decides the card theme and the minted activityId.
  - `platform` 'ios' | 'android': ios writes a LiveActivityRegistration row and returns activityId/expiresAt. android writes a platform:"android" opt-in row (no pushToken) and returns platform android + minted activityId + null expiresAt — opting the fan into Android Live Update pushes for that fixture+club. Any other value is 400 VALIDATION_ERROR.
  - `pushToken` string, nullable: Optional hex ActivityKit token stored for the client call OneSignal.LiveActivities.enter(activityId, pushToken). Omitted on a later POST leaves the stored token in place. The server never sends it to Apple or OneSignal.

## Response `200`

Registered (iOS: expiresAt set; Android: platform android + minted activityId, null expiresAt)

- object
  - `success` true, required
  - `data` union, required
    - object: iOS registration
      - `registered` true, required
      - `activityId` string, required: Per-user (#558): hq:{gameEventId}:{teamId}:{userId}. Minted server-side; pass it verbatim to OneSignal.LiveActivities.enter.
      - `expiresAt` string, date-time, required
    - object: Android opt-in registered (#697): platform:"android" row written — the fan joins the fixture+club Android Live Update audience
      - `registered` true, required
      - `platform` 'android', required
      - `activityId` string, required: Minted per-user id hq:{gameEventId}:{teamId}:{userId}, same scheme as iOS.
      - `expiresAt` unknown, required

## Other responses

- `400`: VALIDATION_ERROR — teamId missing, or not one of the fixture's two clubs
- `401`: UNAUTHORIZED — no valid Clerk session
- `403`: FORBIDDEN — UserSettings.liveScoreUpdates is not enabled
- `404`: NOT_FOUND — no such fixture
- `500`: INTERNAL_ERROR

## Changes

- **2026-11-18** `6de639c52609`: 2 breaking, 2 info
  - request property `platform` was restricted to a list of enum values
  - the `data/oneOf[subschema #2]/activityId` response's property type changed from `null` to `string` for status `200`
  - added the new `android` enum value to the request property `platform`
  - added the new `ios` enum value to the request property `platform`
- **2026-09-24** `01971acf764b`: 5 breaking
  - added `subschema #1, subschema #2` to the `data` response property `oneOf` list for the response status `200`
  - the `data` response's property type changed from `object` to no type for status `200`
  - removed the required property `data/activityId` from the response with the `200` status
  - removed the required property `data/expiresAt` from the response with the `200` status
  - …1 more
- **2026-09-12** `a8df6fe04343`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/changes/api/events/:gameId/live-activity/post.md)

---

[API](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api.md) - [All operations](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/llms.txt) - [OpenAPI document](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/revisions/63735cf90a04?raw)
