Share Media

This endpoint requires authentication. Users can only share their own media files.

Overview

Generate a shareable link for a media item and optionally share it to the Community feed. When shared to community, the media is copied to the public general bucket with watermarking applied to user uploads.

Path Parameters

number

required

The database ID of the media item to share. Get this from GET /api/user/media.

Request Body

Whether to share the media to the global Community feed.

true - Creates a persistent copy in the general bucket and displays in Community
false - Removes any existing community copy and tag assignments

array

Array of tag slugs to apply to the shared media (required when sharing user uploads to community).Example: ["brunette", "solo", "lingerie"]Validation:

At least one tag required for upload images shared to community
Tags must exist in the canonical tags system
Maximum per configuration (typically 10 tags)

boolean

Confirmation that user agrees to community sharing policy (required when sharing user uploads to community).Must be true when shareToCommunity=true for source: "upload" images.

Request Example

{
  "shareToCommunity": true,
  "tags": ["brunette", "solo", "artistic"],
  "policyAgreed": true
}

When shareToCommunity=true

Generate share code - Unique code for the media item
Copy to general bucket:
- Downloads file from user-media bucket
- Applies JOIP watermark to user uploads (images only)
- Uploads to general bucket with unique filename
Create community record - Entry in community_media table
Apply tags - Associates selected tags with the community media
Update media record - Sets isShared=true and shareToCommunity=true

When shareToCommunity=false

Update media record - Sets shareToCommunity=false
Remove community copy:
- Deletes file from general bucket
- Removes community_media record
- Removes all tag assignments

Watermarking

Applies to: User uploads (source: "upload") with watermarkable MIME types Watermarkable types:

image/jpeg
image/png
image/webp

Non-watermarked sources:

smart-caption - AI-generated captions
babecock - Babecock Studio composites
hypnococks - HypnoCocks renders
Videos and GIFs (any source)

The endpoint uses advisory locks to handle concurrent share requests:

Prevents duplicate community records
Atomic updates to existing records
Safe for multiple users or browser tabs

Authorization

Users can only share their own media
Endpoint verifies media.userId matches authenticated user
Returns 404 Not Found if media doesn’t exist or belongs to another user

Response

Unique share code for accessing the media via public URL

Full shareable URL: /shared/media/{shareCode}

string

Public URL of the file in the general bucket (when shareToCommunity=true)

number

Database ID of the community media record (when shareToCommunity=true)

Success Response Example

{
  "shareCode": "abc123def456",
  "shareUrl": "/shared/media/abc123def456",
  "communityUrl": "https://example.supabase.co/storage/v1/object/public/general/beach_photo-a1b2c3d4.jpg",
  "communityMediaId": 789
}

Error Responses

400 Bad Request

Invalid media ID:

{
  "message": "Invalid media ID"
}

Missing policy agreement (for user upload images):

{
  "message": "Policy confirmation is required for upload sharing"
}

Missing tags (for user upload images):

{
  "message": "At least one tag is required for upload sharing"
}

404 Not Found

Media not found or unauthorized:

{
  "message": "Media not found"
}

500 Internal Server Error

Failed to create share link:

{
  "message": "Failed to create share link"
}

General error:

{
  "message": "Failed to share media"
}

Activity Tracking

Successful shares are logged with:

Action: media_shared
Feature: media_gallery
Details: Media ID, share code, community sharing status

Example Usage

cURL

# Share to community with tags
curl -X POST "https://your-domain.com/api/media/456/share" \
  -H "Cookie: connect.sid=your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "shareToCommunity": true,
    "tags": ["brunette", "solo"],
    "policyAgreed": true
  }'

# Share without community (link only)
curl -X POST "https://your-domain.com/api/media/456/share" \
  -H "Cookie: connect.sid=your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{"shareToCommunity": false}'

JavaScript (Fetch API)

// Share to community
const response = await fetch('/api/media/456/share', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  credentials: 'include',
  body: JSON.stringify({
    shareToCommunity: true,
    tags: ['brunette', 'artistic'],
    policyAgreed: true
  })
});

const result = await response.json();
console.log('Share URL:', result.shareUrl);
console.log('Share code:', result.shareCode);

// Get full URL
const fullUrl = `${window.location.origin}${result.shareUrl}`;

React Example with Tag Selection

import { useState } from 'react';

function ShareMediaDialog({ mediaId, source, onShared }) {
  const [shareToCommunity, setShareToCommunity] = useState(true);
  const [selectedTags, setSelectedTags] = useState([]);
  const [policyAgreed, setPolicyAgreed] = useState(false);
  const [sharing, setSharing] = useState(false);

  const isUploadImage = source === 'upload';
  const canShare = !isUploadImage || (selectedTags.length > 0 && policyAgreed);

  const handleShare = async () => {
    setSharing(true);
    try {
      const response = await fetch(`/api/media/${mediaId}/share`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        credentials: 'include',
        body: JSON.stringify({
          shareToCommunity,
          tags: selectedTags,
          policyAgreed
        })
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message);
      }

      const result = await response.json();
      
      // Copy share URL to clipboard
      const fullUrl = `${window.location.origin}${result.shareUrl}`;
      await navigator.clipboard.writeText(fullUrl);
      
      alert('Share link copied to clipboard!');
      onShared?.(result);
    } catch (error) {
      console.error('Share failed:', error);
      alert(`Failed to share: ${error.message}`);
    } finally {
      setSharing(false);
    }
  };

  return (
    <div>
      <h3>Share Media</h3>
      
      <label>
        <input
          type="checkbox"
          checked={shareToCommunity}
          onChange={(e) => setShareToCommunity(e.target.checked)}
        />
        Share to Community Feed
      </label>

      {shareToCommunity && isUploadImage && (
        <div>
          <div>
            <label>Select Tags (required):</label>
            <TagSelector
              selected={selectedTags}
              onChange={setSelectedTags}
            />
          </div>

          <label>
            <input
              type="checkbox"
              checked={policyAgreed}
              onChange={(e) => setPolicyAgreed(e.target.checked)}
            />
            I agree to the community sharing policy
          </label>
        </div>
      )}

      <button onClick={handleShare} disabled={sharing || !canShare}>
        {sharing ? 'Sharing...' : 'Share'}
      </button>
    </div>
  );
}

Unshare from Community

// Remove from community while keeping share link
const response = await fetch('/api/media/456/share', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    shareToCommunity: false
  })
});

const result = await response.json();
console.log('Media unshared from community');
// Share code still exists for direct link sharing

Completely remove sharing:

Deletes share code
Removes community copy if shared
Sets isShared=false and shareToCommunity=false

Share by storage path instead of database ID:

Accepts filePath in request body
Creates database record if needed
Same sharing behavior otherwise

Notes

Share codes are unique and unguessable (UUID-based)
Community copies are persistent and remain even if original is deleted from user’s vault
Watermarking is applied automatically to user upload images
Generated media (Smart Captions, Babecock, HypnoCocks) is not watermarked
Tag assignments are only stored for community media, not the original
Multiple concurrent share requests are handled safely with database locks
Shared media appears in the Community feed at /community

Overview

Sessions

Media

AI Services

Community

Credits

Babecock

Reddit Integration

Overview

Path Parameters

Request Body

Request Example

When shareToCommunity=true

When shareToCommunity=false

Watermarking

Authorization

Response

Success Response Example

Error Responses

400 Bad Request

404 Not Found

500 Internal Server Error

Activity Tracking

Example Usage

cURL

JavaScript (Fetch API)

React Example with Tag Selection

Unshare from Community

Notes

​Overview

​Path Parameters

​Request Body

​Request Example

​Community Sharing Process

​When shareToCommunity=true

​When shareToCommunity=false

​Watermarking

​Concurrent Share Handling

​Authorization

​Response

​Success Response Example

​Error Responses

​400 Bad Request

​404 Not Found

​500 Internal Server Error

​Activity Tracking

​Example Usage

​cURL

​JavaScript (Fetch API)

​React Example with Tag Selection

​Unshare from Community

​Related Endpoints

​DELETE /api/media/:id/share

​POST /api/user/media/share

​Notes

Overview

Path Parameters

Request Body

Request Example

Community Sharing Process

When shareToCommunity=true

When shareToCommunity=false

Watermarking

Concurrent Share Handling

Authorization

Response

Success Response Example

Error Responses

400 Bad Request

404 Not Found

500 Internal Server Error

Activity Tracking

Example Usage

cURL

JavaScript (Fetch API)

React Example with Tag Selection

Unshare from Community

Related Endpoints

DELETE /api/media/:id/share

POST /api/user/media/share

Notes