Skip to main content
POST
/
sessions
/
by-slug
/
:slug
/
viewers
Manage Viewers
curl --request POST \
  --url https://api.example.com/sessions/by-slug/:slug/viewers \
  --header 'Content-Type: application/json' \
  --data '
{
  "viewers": [
    {
      "id": "<string>",
      "lastSeenAt": "<string>",
      "requests": 123,
      "ip": "<string>"
    }
  ],
  "viewerId": "<string>"
}
'
{
  "ok": true,
  "kickedViewerIds": [
    "<string>"
  ]
}
Manage active viewers and kick viewers from a session.

​
Update Active Viewers

Update the list of currently active viewers for a session.

​
Endpoint

POST /sessions/by-slug/:slug/viewers

​
Path Parameters

​
slug
string
required
The session slug (format: adjective-noun-number)

​
Request Body

​
viewers
array
required
Array of active viewer objects
​
id
string
required
Unique viewer identifier
​
lastSeenAt
string
required
ISO 8601 timestamp of the viewer’s last activity
​
requests
number
required
Total number of requests made by this viewer
​
ip
string
Viewer’s IP address (optional)

​
Response

​
ok
boolean
required
Whether the update was successful

​
Example Request

curl -X POST https://control.wormkey.io/sessions/by-slug/quiet-lime-42/viewers \
  -H "Content-Type: application/json" \
  -d '{
    "viewers": [
      {
        "id": "viewer_abc123",
        "lastSeenAt": "2026-03-03T15:35:00.000Z",
        "requests": 42,
        "ip": "203.0.113.42"
      },
      {
        "id": "viewer_xyz789",
        "lastSeenAt": "2026-03-03T15:36:00.000Z",
        "requests": 18,
        "ip": "203.0.113.89"
      }
    ]
  }'

​
Example Response

{
  "ok": true
}

​
Kick Viewer

Remove a viewer from the session and add them to the kicked list to prevent rejoining.

​
Endpoint

POST /sessions/by-slug/:slug/kick

​
Path Parameters

​
slug
string
required
The session slug (format: adjective-noun-number)

​
Request Body

​
viewerId
string
required
The ID of the viewer to kick from the session

​
Response

​
ok
boolean
required
Whether the kick was successful
​
kickedViewerIds
string[]
required
Updated array of all kicked viewer IDs

​
Example Request

curl -X POST https://control.wormkey.io/sessions/by-slug/quiet-lime-42/kick \
  -H "Content-Type: application/json" \
  -d '{
    "viewerId": "viewer_abc123"
  }'

​
Example Response

{
  "ok": true,
  "kickedViewerIds": ["viewer_abc123"]
}

​
Behavior

  • The viewer is removed from the activeViewers list
  • The viewer ID is added to the kickedViewerIds list (if not already present)
  • Kicked viewers cannot rejoin the session

​
Error Response

Both endpoints return a 404 error if the session is not found: 
{
  "error": "Session not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us