Fanvue API Skill

Integrate with the Fanvue creator platform to manage chats, posts, subscribers, earnings insights, and media content.

Prerequisites

1. Create an OAuth Application

Go to the [Fanvue Developer Portal]()

Create a new OAuth application

Note your Client ID and Client Secret

Configure your Redirect URI (e.g., ) ### 2. Environment Variables Set these environment variables: __CODE_BLOCK_0__ --- ## Authentication Fanvue uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange). All API requests require: - **Authorization Header**: Bearer - **API Version Header**: X-Fanvue-API-Version: 2025-06-26 ### OAuth Scopes Request these scopes based on your needs: | Scope | Access | |-------|--------| | openid | OpenID Connect authentication | | offline_access | Refresh token support | | offline | Offline access | | read:self | Read authenticated user profile | | read:chat | Read chat conversations | | write:chat | Send messages, update chats | | read:post | Read posts | | write:post | Create posts | | read:creator | Read subscriber/follower data | | read:media | Read media vault | | write:tracking_links | Manage campaign links | | read:insights | Read earnings/analytics (creator accounts) | | read:subscribers | Read subscriber lists (creator accounts) | > **Note**: Some endpoints (subscribers, insights, earnings) require a **creator account** and may need additional scopes not listed in the public documentation. ### Quick Auth Flow __CODE_BLOCK_1__ __CODE_BLOCK_2__ --- ## API Base URL All API requests go to:

Standard Request Headers

const headers = {
  'Authorization': `Bearer ${accessToken}`,
  'X-Fanvue-API-Version': '2025-06-26',
  'Content-Type': 'application/json',
};

---

Agent Automation

These workflows are designed for AI agents automating Fanvue creator accounts.

Accessing Images (with Signed URLs)

The basic /media endpoint only returns metadata. To get actual viewable URLs, use the variants query parameter:

// Step 1: List all media
const list = await fetch('', { headers });
const { data } = await list.json();

// Step 2: Get signed URLs for a specific media item
const media = await fetch(
  ` 
  { headers }
);
const { variants } = await media.json();

// variants = [
//   { variantType: 'main', url: '' },
//   { variantType: 'thumbnail', url: '...' },
//   { variantType: 'blurred', url: '...' }
// ]

Variant Types:

• main - Full resolution original


• thumbnail - Optimized preview (smaller)


• blurred - Censored version for teasers

Creating a Post with Media

// Step 1: Have existing media UUIDs from vault
const mediaIds = ['media-uuid-1', 'media-uuid-2'];

// Step 2: Create post
const response = await fetch('', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    text: 'Check out my new content! 🔥',
    mediaIds,
    audience: 'subscribers',  // or 'followers-and-subscribers'
    // Optional:
    price: null,              // Set for pay-per-view
    publishAt: null,          // Set for scheduled posts
  }),
});

Audience Options:

Value

Who Can See

subscribers	Paid subscribers only
followers-and-subscribers	Both free followers and subscribers

Sending Messages with Media

// Get subscriber list for decision making
const subs = await fetch('', { headers });
const { data: subscribers } = await subs.json();

// Get top spenders for VIP targeting
const vips = await fetch('', { headers });
const { data: topSpenders } = await vips.json();

// Send personalized message with media
await fetch('', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuid: subscribers[0].userUuid,
    content: 'Thanks for being a subscriber! Here\'s something special for you 💕',
    mediaIds: ['vault-media-uuid'],  // Attach media from vault
  }),
});

// Or send to multiple subscribers at once
await fetch('', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuids: subscribers.map(s => s.userUuid),
    content: 'New exclusive content just dropped! 🎉',
    mediaIds: ['vault-media-uuid'],
  }),
});

Agent Decision Context

For effective automation, gather this context:

interface AutomationContext {
  // Current media in vault
  media: {
    uuid: string;
    name: string;
    type: 'image' | 'video';
    description: string;  // AI-generated caption
    signedUrl: string;    // From variants query
  }[];
  
  // Audience data
  subscribers: {
    uuid: string;
    name: string;
    subscribedAt: string;
    tier: string;
  }[];
  
  // Engagement signals
  topSpenders: {
    uuid: string;
    totalSpent: number;
  }[];
  
  // Recent earnings for trend analysis
  earnings: {
    period: string;
    total: number;
    breakdown: { type: string; amount: number }[];
  };
}

---

Core Operations

Get Current User

const response = await fetch('', { headers });
const user = await response.json();

List Chats

const response = await fetch('', { headers });
const { data, pagination } = await response.json();

Send a Message

const response = await fetch('', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuid: 'user-uuid-here',
    content: 'Hello! Thanks for subscribing!',
  }),
});

Create a Post

const response = await fetch('', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    content: 'New content available!',
    // Add media IDs, pricing, etc.
  }),
});

Get Earnings

const response = await fetch('', { headers });
const earnings = await response.json();

List Subscribers

const response = await fetch('', { headers });
const { data } = await response.json();

---

API Reference

See api-reference.md for the complete endpoint documentation.

---

Token Refresh

Access tokens expire. Use the refresh token to get new ones:

const response = await fetch('', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    client_id: process.env.FANVUE_CLIENT_ID,
    client_secret: process.env.FANVUE_CLIENT_SECRET,
    refresh_token: currentRefreshToken,
  }),
});

const newTokens = await response.json();

---

Error Handling

Common HTTP status codes:

Status

Meaning

200	Success
400	Bad request - check your parameters
401	Unauthorized - token expired or invalid
403	Forbidden - missing required scope
404	Resource not found
429	Rate limited - slow down requests

---

Resources

• [Fanvue API Documentation]()
• [OAuth 2.0 Guide]()
• [Developer Portal]()
• [Fanvue App Starter Kit]()