Skip to main content
POST
/
api
/
sessions
/
:id
/
share
curl -X POST "https://app.joip.io/api/sessions/123/share" \
  -H "Content-Type: application/json" \
  -H "Cookie: connect.sid=YOUR_SESSION_COOKIE"

{
  "shareCode": "a3f8b2c1-9e4d-4a7b-8c3d-1f2e3a4b5c6d",
  "shareUrl": "https://app.joip.io/shared/a3f8b2c1-9e4d-4a7b-8c3d-1f2e3a4b5c6d?r=abc123",
  "referralCode": "abc123"
}

​
Authentication

This endpoint requires authentication. Users can only share sessions they own.

​
Path Parameters

​
id
integer
required
The unique session ID to share

​
Request Body

​
userId
string
Optional user ID for user-specific shares (rarely used)

​
Response

Returns a share code, shareable URL, and referral code.
​
shareCode
string
UUID v4 share code for accessing the session
​
shareUrl
string
Complete shareable URL including referral tracking
​
referralCode
string
Your referral code embedded in the share URL
curl -X POST "https://app.joip.io/api/sessions/123/share" \
  -H "Content-Type: application/json" \
  -H "Cookie: connect.sid=YOUR_SESSION_COOKIE"

{
  "shareCode": "a3f8b2c1-9e4d-4a7b-8c3d-1f2e3a4b5c6d",
  "shareUrl": "https://app.joip.io/shared/a3f8b2c1-9e4d-4a7b-8c3d-1f2e3a4b5c6d?r=abc123",
  "referralCode": "abc123"
}

​
Behavior

  • If the session already has a share code, the existing code is returned
  • Creating a share automatically sets isPublic: true on the session
  • The share URL includes a referral parameter (?r=) for tracking
  • Share codes are UUID v4 format, providing unguessable URLs for privacy
  • Recipients can access the session at the provided URL without authentication for preview
  • Full playback requires authentication
  • GET /api/shared/:shareCode/preview - Public preview endpoint (no auth)
  • GET /api/shared/:shareCode - Full session access (requires auth)
  • GET /api/shared/media/:shareCode - Access shared session media

​
Notes

  • Activity is tracked for analytics
  • Referral codes help track user acquisition and sharing patterns
  • Share codes remain valid unless the session is deleted
  • Deleting a session automatically removes all associated share codes

Build docs developers (and LLMs) love

Get started for freeTalk to us