# Welcome

# Welcome to the Fanvue API

The Fanvue API gives you direct access to your creator platform data and tools. Whether you're a content creator looking to build custom workflows or an agency managing multiple creators, our API helps you connect your existing tools and automate your processes.

## What can you build?

Think of the Fanvue API as a bridge between your creative work and the tools you already use. You can connect your CRM system to automatically sync subscriber data, build custom dashboards that show exactly the metrics you care about, or create scripts that handle routine tasks like sending welcome messages to new subscribers.

Many creators use our API to build automated engagement tools that help them stay connected with their audience without the manual work. Agency managers often integrate it with their existing systems to get a unified view across all the creators they manage.

## How it works

The API uses simple HTTP requests with an API key for authentication. You can access user profiles, chat conversations, subscriber lists, and creator data through straightforward endpoints. Everything is designed to be secure and respect the permissions you set up.

## Getting started

You'll need an [API key](/docs/authentication/api-keys) to begin. Once you have that, you can start making requests to explore your data. If you're ready to build something specific, our [quickstart guide](/docs/introduction/quick-start) walks you through creating your first integration step by step.

The possibilities are entirely up to you and what would make your creator workflow more efficient.


# Quick Start

# Quick Start Guide

Welcome to the Fanvue API! In just 10 minutes, you'll have a working Next.js application that securely fetches and displays your profile information using server-side API calls.

## What is the Fanvue API?

The Fanvue API provides access to a powerful creator platform with these core capabilities:

* **User Management** - Access profile information and account details
* **Chat Functionality** - Build messaging features and manage conversations
* **Social Features** - Handle followers, subscribers, and community interactions
* **Agency Tools** - Manage creators and handle agency-related operations

Whether you're building a custom dashboard, integrating with existing tools, or creating new experiences for creators and fans, our API has you covered.

## What You'll Build

In this tutorial, you'll create a modern Next.js application that:

* Securely connects to the Fanvue API using server-side authentication
* Fetches your profile information through a backend API route
* Displays your user details in a clean, responsive React interface
* Handles loading states and errors gracefully
* Follows security best practices by keeping API keys on the server

By the end, you'll understand how to build secure API integrations, work with Next.js App Router, and create modern React applications.

<Note>
  ##### Prerequisites

  Before you start, make sure you have:

  * Basic knowledge of JavaScript and React
  * Node.js 18 or later installed on your computer ([download here](https://nodejs.org/))
  * A terminal or command prompt
  * A text editor or IDE (VS Code recommended)
  * An API key from your Fanvue representative (contact them if you don't have one yet)
  * API version "2025-06-26" (the current stable version used in this tutorial)
</Note>

**New to React or Next.js?** Don't worry! This tutorial includes detailed explanations for each step.

## Step-by-Step Tutorial

### Step 1: Create Your Next.js Project

First, let's create a new Next.js project with all the modern features enabled. Open your terminal and run this command:

```bash
npx create-next-app@latest fanvue-profile --typescript --tailwind --eslint --app
```

**What's happening here?**

* `create-next-app@latest` creates a new Next.js project with the latest version
* `fanvue-profile` is the name of your project folder
* `--typescript` enables TypeScript for better code quality and autocomplete
* `--tailwind` includes Tailwind CSS for easy styling
* `--eslint` adds ESLint for code linting and best practices
* `--app` uses the modern App Router (instead of the older Pages Router)

When prompted, choose these options:

* **Would you like to use `src/` directory?** → No
* **Would you like to use App Router?** → Yes (should be pre-selected)
* **Would you like to customize the default import alias?** → No

After the installation completes (this may take a minute), navigate to your project:

```bash
cd fanvue-profile
```

**Let's explore what was created:**
Your project now has this structure:

```
fanvue-profile/
├── app/                    # App Router directory (this is where we'll work)
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout component
│   └── page.tsx           # Home page component
├── public/                # Static assets
├── next.config.js         # Next.js configuration
├── package.json           # Dependencies and scripts
└── tailwind.config.ts     # Tailwind CSS configuration
```

### Step 2: Set Up Your API Key Securely

Now we need to configure your API key. Unlike client-side applications, Next.js allows us to store sensitive information securely on the server using environment variables.

Create a new file called `.env.local` in your project root (the same folder as `package.json`):

```bash
touch .env.local
```

Open `.env.local` in your text editor and add your API key:

```bash
FANVUE_API_KEY=YOUR_API_KEY_HERE
```

<Warning>
  ##### Security Note: - The `.env.local` file keeps your API key secure on the server - Never

  commit this file to version control (it's automatically ignored by Git) - Environment variables
  starting with `NEXT_PUBLIC_` are exposed to the browser, but ours isn't, so it stays private -
  Replace `YOUR_API_KEY_HERE` with your actual API key from your Fanvue representative
</Warning>

**What's happening here?**

* `.env.local` files are automatically loaded by Next.js
* Your API key will be available as `process.env.FANVUE_API_KEY` in server-side code
* This approach is much more secure than hardcoding keys in your source code

### Step 3: Create a Server-Side API Route

Now we'll create a server-side API route that securely calls the Fanvue API. This keeps your API key hidden from users and provides better security.

First, create the directory structure for your API route:

```bash
mkdir -p app/api/profile
```

Now create the API route file `app/api/profile/route.ts`:

```typescript
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  try {
    // Get the API key from environment variables
    const apiKey = process.env.FANVUE_API_KEY;

    if (!apiKey) {
      return NextResponse.json({ error: "API key not configured" }, { status: 500 });
    }

    // Make the request to Fanvue API
    const response = await fetch("https://api.fanvue.com/users/me", {
      method: "GET",
      headers: {
        "X-Fanvue-API-Key": apiKey,
        "X-Fanvue-API-Version": "2025-06-26",
        "Content-Type": "application/json",
      },
    });

    // Check if the request was successful
    if (!response.ok) {
      return NextResponse.json(
        { error: `Fanvue API error: ${response.status} ${response.statusText}` },
        { status: response.status }
      );
    }

    // Parse and return the profile data
    const profileData = await response.json();
    return NextResponse.json(profileData);
  } catch (error) {
    console.error("Profile API error:", error);
    return NextResponse.json({ error: "Failed to fetch profile" }, { status: 500 });
  }
}
```

**What's happening here?**

* We export a `GET` function that handles HTTP GET requests to `/api/profile`
* The API key is securely accessed from `process.env.FANVUE_API_KEY`
* We include the `X-Fanvue-API-Version` header to specify which version of the API to use
* We make the request to Fanvue API server-to-server (more secure)
* Error handling provides helpful feedback without exposing sensitive details
* The response is returned as JSON that our frontend can consume

**App Router API Routes:**

* Routes are defined by creating `route.ts` files in the `app/api/` directory
* The folder structure determines the URL path (`app/api/profile/route.ts` → `/api/profile`)
* Named exports (`GET`, `POST`, etc.) handle different HTTP methods

### Step 4: Create the Profile Display Component

Now let's create a React component that fetches and displays your profile data. We'll replace the default content in `app/page.tsx`:

```typescript
'use client'

import { useEffect, useState } from 'react'

interface Profile {
  uuid: string
  email: string
  handle: string
}

interface ApiError {
  error: string
}

export default function ProfilePage() {
  const [profile, setProfile] = useState<Profile | null>(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<string | null>(null)

  useEffect(() => {
    async function fetchProfile() {
      try {
        const response = await fetch('/api/profile')

        if (!response.ok) {
          const errorData: ApiError = await response.json()
          throw new Error(errorData.error || `HTTP ${response.status}`)
        }

        const profileData: Profile = await response.json()
        setProfile(profileData)
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Failed to fetch profile')
      } finally {
        setLoading(false)
      }
    }

    fetchProfile()
  }, [])

  if (loading) {
    return (
      <main className="min-h-screen bg-gray-50 flex items-center justify-center p-4">
        <div className="bg-white rounded-lg shadow-lg p-8 max-w-md w-full">
          <h1 className="text-2xl font-bold text-gray-800 mb-6">My Fanvue Profile</h1>
          <p className="text-gray-600 italic">Loading your profile...</p>
        </div>
      </main>
    )
  }

  if (error) {
    return (
      <main className="min-h-screen bg-gray-50 flex items-center justify-center p-4">
        <div className="bg-white rounded-lg shadow-lg p-8 max-w-md w-full">
          <h1 className="text-2xl font-bold text-gray-800 mb-6">My Fanvue Profile</h1>
          <div className="bg-red-50 border border-red-200 rounded-lg p-4">
            <h3 className="text-red-800 font-semibold mb-2">Error Loading Profile</h3>
            <p className="text-red-700">{error}</p>
            <p className="text-red-600 text-sm mt-2">
              Check the browser console for more details.
            </p>
          </div>
        </div>
      </main>
    )
  }

  return (
    <main className="min-h-screen bg-gray-50 flex items-center justify-center p-4">
      <div className="bg-white rounded-lg shadow-lg p-8 max-w-md w-full">
        <h1 className="text-2xl font-bold text-gray-800 mb-6">My Fanvue Profile</h1>
        {profile && (
          <div className="space-y-4">
            <h2 className="text-xl font-semibold text-gray-700">Profile Information</h2>
            <div className="space-y-3">
              <p>
                <span className="font-medium text-gray-600">User ID:</span>{' '}
                <span className="text-gray-800">{profile.uuid}</span>
              </p>
              <p>
                <span className="font-medium text-gray-600">Email:</span>{' '}
                <span className="text-gray-800">{profile.email}</span>
              </p>
              <p>
                <span className="font-medium text-gray-600">Handle:</span>{' '}
                <span className="text-gray-800">@{profile.handle}</span>
              </p>
            </div>
          </div>
        )}
      </div>
    </main>
  )
}
```

**What's happening here?**

* `'use client'` directive marks this as a Client Component (needed for hooks and interactivity)
* We use React hooks (`useState`, `useEffect`) to manage component state
* TypeScript interfaces define the shape of our data for better type safety
* `useEffect` runs when the component mounts to fetch the profile data
* We call our local API route (`/api/profile`) instead of the external API directly
* Tailwind CSS classes provide clean, responsive styling
* Loading states and error handling give users clear feedback

**React Hooks Explained:**

* `useState` manages component state (profile data, loading, errors)
* `useEffect` handles side effects like API calls when the component loads
* The dependency array `[]` means this effect runs once on mount

### Step 5: Test Your Application

Now let's start your Next.js development server and test your application!

1. **Start the development server:**

```bash
npm run dev
```

You should see output like:

```
▲ Next.js 14.0.0
- Local:        http://localhost:3000
- Environments: .env.local

✓ Ready in 2.3s
```

2. **Open your application:**

Visit `http://localhost:3000` in your web browser.

3. **Check the results:**

   * **Success**: You'll see your profile information displayed in a clean card layout
   * **Loading**: You should briefly see "Loading your profile..." before data appears
   * **Error**: Any issues will be displayed in a red error box

4. **Troubleshooting common issues:**

   * **"API key not configured"**:

     * Check that `.env.local` exists in your project root
     * Verify you've replaced `YOUR_API_KEY_HERE` with your actual API key
     * Restart the dev server (`Ctrl+C` then `npm run dev` again)

   * **Port 3000 already in use**:

     ```bash
     npm run dev -- -p 3001
     ```

   * **TypeScript errors**:

     * Make sure you're using `.tsx` extension for the page file
     * Check that all imports are correct

   * **"Failed to fetch profile"**:

     * Check your internet connection
     * Verify your API key is valid with your Fanvue representative
     * Check the browser's Network tab (F12 → Network) for more details

   * **Styles not loading**:
     * Ensure Tailwind CSS was installed during project creation
     * Try refreshing the page

**Development Tips:**

* The development server automatically reloads when you save files
* Check the terminal where you ran `npm run dev` for server-side errors
* Use browser DevTools (F12) to inspect client-side issues

## Complete Working Example

Here's your complete Next.js project structure with all the files you need:

### Project Structure

```
fanvue-profile/
├── .env.local                 # Your API key (create this)
├── app/
│   ├── api/
│   │   └── profile/
│   │       └── route.ts       # API route (create this)
│   ├── globals.css            # Global styles (already exists)
│   ├── layout.tsx             # Root layout (already exists)
│   └── page.tsx               # Main page (replace existing)
├── next.config.js             # Next.js config (already exists)
├── package.json               # Dependencies (already exists)
└── tailwind.config.ts         # Tailwind config (already exists)
```

### `.env.local`

```bash
FANVUE_API_KEY=YOUR_API_KEY_HERE
```

### `app/api/profile/route.ts`

```typescript
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  try {
    // Get the API key from environment variables
    const apiKey = process.env.FANVUE_API_KEY;

    if (!apiKey) {
      return NextResponse.json({ error: "API key not configured" }, { status: 500 });
    }

    // Make the request to Fanvue API
    const response = await fetch("https://api.fanvue.com/users/me", {
      method: "GET",
      headers: {
        "X-Fanvue-API-Key": apiKey,
        "X-Fanvue-API-Version": "2025-06-26",
        "Content-Type": "application/json",
      },
    });

    // Check if the request was successful
    if (!response.ok) {
      const errorText = await response.text();
      return NextResponse.json(
        { error: `Fanvue API error: ${response.status} ${response.statusText}` },
        { status: response.status }
      );
    }

    // Parse and return the profile data
    const profileData = await response.json();
    return NextResponse.json(profileData);
  } catch (error) {
    console.error("Profile API error:", error);
    return NextResponse.json({ error: "Failed to fetch profile" }, { status: 500 });
  }
}
```

### `app/page.tsx`

```typescript
'use client'

import { useEffect, useState } from 'react'

interface Profile {
  uuid: string
  email: string
  handle: string
}

interface ApiError {
  error: string
}

export default function ProfilePage() {
  const [profile, setProfile] = useState<Profile | null>(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<string | null>(null)

  useEffect(() => {
    async function fetchProfile() {
      try {
        const response = await fetch('/api/profile')

        if (!response.ok) {
          const errorData: ApiError = await response.json()
          throw new Error(errorData.error || `HTTP ${response.status}`)
        }

        const profileData: Profile = await response.json()
        setProfile(profileData)
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Failed to fetch profile')
      } finally {
        setLoading(false)
      }
    }

    fetchProfile()
  }, [])

  if (loading) {
    return (
      <main className="min-h-screen bg-gray-50 flex items-center justify-center p-4">
        <div className="bg-white rounded-lg shadow-lg p-8 max-w-md w-full">
          <h1 className="text-2xl font-bold text-gray-800 mb-6">My Fanvue Profile</h1>
          <p className="text-gray-600 italic">Loading your profile...</p>
        </div>
      </main>
    )
  }

  if (error) {
    return (
      <main className="min-h-screen bg-gray-50 flex items-center justify-center p-4">
        <div className="bg-white rounded-lg shadow-lg p-8 max-w-md w-full">
          <h1 className="text-2xl font-bold text-gray-800 mb-6">My Fanvue Profile</h1>
          <div className="bg-red-50 border border-red-200 rounded-lg p-4">
            <h3 className="text-red-800 font-semibold mb-2">Error Loading Profile</h3>
            <p className="text-red-700">{error}</p>
            <p className="text-red-600 text-sm mt-2">
              Check the browser console for more details.
            </p>
          </div>
        </div>
      </main>
    )
  }

  return (
    <main className="min-h-screen bg-gray-50 flex items-center justify-center p-4">
      <div className="bg-white rounded-lg shadow-lg p-8 max-w-md w-full">
        <h1 className="text-2xl font-bold text-gray-800 mb-6">My Fanvue Profile</h1>
        {profile && (
          <div className="space-y-4">
            <h2 className="text-xl font-semibold text-gray-700">Profile Information</h2>
            <div className="space-y-3">
              <p>
                <span className="font-medium text-gray-600">User ID:</span>{' '}
                <span className="text-gray-800">{profile.uuid}</span>
              </p>
              <p>
                <span className="font-medium text-gray-600">Email:</span>{' '}
                <span className="text-gray-800">{profile.email}</span>
              </p>
              <p>
                <span className="font-medium text-gray-600">Handle:</span>{' '}
                <span className="text-gray-800">@{profile.handle}</span>
              </p>
            </div>
          </div>
        )}
      </div>
    </main>
  )
}
```

**Quick Setup Commands:**

```bash
# Create the project
npx create-next-app@latest fanvue-profile --typescript --tailwind --eslint --app
cd fanvue-profile

# Create the API route directory
mkdir -p app/api/profile

# Create and edit your files
touch .env.local
# Then add your API key to .env.local
# Replace the contents of app/page.tsx
# Create app/api/profile/route.ts

# Start the development server
npm run dev
```

## Congratulations!

You've successfully built your first Fanvue API integration using modern Next.js! You now understand:

* **Server-side API Security**: How to keep API keys secure using environment variables and server-side routes
* **Next.js App Router**: How to create API routes and React components using the latest Next.js features
* **TypeScript Integration**: How to use TypeScript for better code quality and developer experience
* **Modern React Patterns**: How to manage state, handle loading states, and display data with hooks
* **Error Handling**: How to gracefully handle and display errors in both client and server code

## Next Steps

Ready to build more advanced features? Here are some Next.js-specific ideas to extend your application:

### Intermediate Features

* **Server Components**: Convert some parts to Server Components for better performance
* **Streaming & Suspense**: Add streaming responses for better perceived performance
* **Middleware**: Add API middleware for request logging and rate limiting
* **Custom Hooks**: Extract your API logic into reusable custom hooks

### Advanced Features

* **Next.js Caching**: Implement caching strategies for your API responses
* **Real-time Updates**: Add WebSocket support for live profile updates
* **Static Generation**: Pre-build profile pages at build time using ISR
* **Edge Runtime**: Deploy your API routes to the edge for global performance

### API Exploration

* **Chat Integration**: Build a messaging interface using the chat endpoints
* **Follower Management**: Create components for follower/following relationships
* **File Upload**: Add profile image upload capabilities
* **Pagination**: Implement paginated lists for followers, chats, etc.

### Production Readiness

* **Error Boundaries**: Add React error boundaries for better error handling
* **Loading Skeletons**: Create skeleton screens for better UX
* **SEO Optimization**: Add proper meta tags and structured data
* **Performance Monitoring**: Integrate analytics and performance tracking

Check out our other documentation sections to learn about:

* [API Scopes](/docs/scopes) - Understanding permissions and access levels
* [Rate Limits](/docs/rate-limit) - Managing your API usage effectively

**Next.js Resources:**

* [Next.js Documentation](https://nextjs.org/docs) - Official Next.js guides
* [App Router Guide](https://nextjs.org/docs/app) - Deep dive into App Router features
* [React Documentation](https://react.dev) - Learn more about React patterns

Happy coding! 🚀


# Overview

# Authentication Overview

## Why Authentication Matters

When you use the Fanvue API, authentication is your digital key that unlocks access to our platform. Here's why it's essential:

**Identity Verification**\
Authentication confirms who you are, ensuring that only authorized applications and users can access creator content and platform features.

**Access Control**\
Different applications need different levels of access. Authentication ensures you only see and modify the data you're supposed to, protecting both creators and fans.

**Data Protection**\
Your authentication credentials act as a secure barrier, preventing unauthorized access to sensitive information like personal details, financial data, and private content.

**Usage Monitoring**\
Authentication helps us monitor API usage, prevent abuse, and ensure fair access to our services for all developers and creators.

## How Fanvue API Authentication Works

The Fanvue API uses **API Keys** for authentication - a simple, secure method that's perfect for server-to-server communication.


# API Keys

# API Keys

## What is an API Key?

An API Key is a unique identifier that acts like a password for your application. It's a long string of characters that you include with every request to prove your identity.

Think of it like a VIP pass at an event - you show your pass (API key) at the door (with each API request), and the security guard (our servers) checks if it's valid and what areas you're allowed to access.

## Getting and managing API Keys

To request an API key for your application:

1. Go to [https://www.fanvue.com/api-keys](https://www.fanvue.com/api-keys)
2. Click **New API key**
3. To revoke your key click the bin icon in the table

<Frame background="subtle">
  <img src="file:bd26ffa9-98cf-408b-886f-2ad76fa10df7" alt="API Keys" />
</Frame>

## API Key Limitations and Scopes

**One API Key Per User**
Each user can only have one active API key at a time. If you need a new API key, your existing one will be replaced.

**Fixed Scopes**
Every API key comes with a specific set of scopes - these determine which resources and actions your application can access. Scopes define permissions like reading user data, accessing chat features, or managing creator content.

**Scopes Cannot Be Changed**
Once an API key is issued with specific scopes, those permissions cannot be modified. If you need access to different resources or additional permissions, you'll need to request a new API key with the appropriate scopes from your Fanvue representative.

## Keeping Your API Keys Secure

Your API key is like a password - it gives access to your account and data. Here's how to keep it safe:

**Never Share Your Keys**

* Don't include API keys in emails, chat messages, or documentation
* Don't share keys with team members who don't need API access
* Use environment variables instead of hardcoding keys in your application

**Avoid Public Exposure**

* Never commit API keys to public GitHub repositories or version control
* Don't include keys in client-side code (websites, mobile apps) where users can see them
* Be careful when sharing code snippets or asking for help online

**Use Environment Variables**
Store your API key in environment variables rather than directly in your code:

```bash
# In your .env file
FANVUE_API_KEY=your_api_key_here
```

**Monitor Usage**

* Regularly check your API usage to spot any unexpected activity
* Contact us immediately if you suspect your key has been compromised

## Making Requests with Your API Key

To authenticate your requests, include your API key in the `X-Fanvue-API-Key` header:

### Example Request

```bash
curl -X GET "https://api.fanvue.com/users/me" \
  -H "X-Fanvue-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"
```

```javascript
// Using fetch in JavaScript
const response = await fetch("https://api.fanvue.com/users/me", {
  headers: {
    "X-Fanvue-API-Key": process.env.FANVUE_API_KEY,
    "Content-Type": "application/json",
  },
});

const data = await response.json();
```

```python
# Using requests in Python
import requests
import os

headers = {
    'X-Fanvue-API-Key': os.getenv('FANVUE_API_KEY'),
    'Content-Type': 'application/json'
}

response = requests.get('https://api.fanvue.com/users/me', headers=headers)
data = response.json()
```

**Important Notes:**

* Always include the `X-Fanvue-API-Key` header in every request
* Use HTTPS only - never send API keys over unencrypted connections
* Store your API key securely using environment variables or secure configuration management


# Scopes

# Scopes

## What are Scopes?

Scopes define what your API key can access and do within the Fanvue platform. Think of them as permissions that determine which resources your application can read from or write to.

When you request an API key, you'll need to specify which scopes you need based on your application's requirements. This ensures your application only has access to the data and features it actually needs, following the principle of least privilege for better security.

## How Scopes Work

* **Permission Control**: Each scope grants access to specific resources and actions
* **Request Validation**: Every API request checks if your key has the required scopes
* **Error Handling**: Requests without sufficient scopes return a `403 Forbidden` error
* **Fixed Assignment**: Scopes are set when your API key is issued and cannot be changed later

## Available Scopes

The following table lists all available scopes organized by resource:

| Resource | Scopes                    |
| -------- | ------------------------- |
| User     | `read:self`               |
| Chat     | `read:chat`, `write:chat` |
| Fan      | `read:fan`                |
| Creator  | `read:creator`            |

### Scope Descriptions

**`read:self`**\
Access your own user profile information, including basic account details and settings.

**`read:chat`**\
Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.

**`write:chat`**\
Create new chats and send messages. This scope is required for any chat-related actions that modify data.

**`read:fan`**\
Access fan-related data and information within the platform.

**`read:creator`**\
Access creator profiles, content, and creator-specific information.

## Requesting Scopes

When requesting an API key from your Fanvue representative, be sure to:

1. **List all required scopes** for your application
2. **Explain your use case** to help our team understand why each scope is needed
3. **Follow the principle of least privilege** - only request scopes you actually need

If you need additional scopes later, you'll need to request a new API key as existing scopes cannot be modified.

## Error Handling

If your API key doesn't have the required scopes for a request, you'll receive:

```json
{
  "error": "Insufficient scopes"
}
```

This response comes with a `403 Forbidden` HTTP status code. Make sure your API key includes all necessary scopes for the endpoints you plan to use.


# Rate Limits

# Rate Limits

Rate limits are like traffic lights for API requests - they keep our servers running smoothly, ensure fair access for everyone, prevent abuse, and maintain reliable service quality.

## Current Limits

By default, each API key can make **100 requests per 60 seconds**. This means you get 100 tokens in your bucket, and it refills completely every minute.

## Dive deeper

If you want to learn more about rate limits, how it's implemented and how to work with them, you can read all about it in our [Advanced Rate Limits Guide](/docs/advanced/working-with-rate-limits).


# Overview

# API Versioning

API versioning ensures backward compatibility and allows us to introduce improvements without breaking existing integrations.

The current version of the Fanvue API is `2025-06-26`.

## Version Header

All API requests must include the `X-Fanvue-API-Version` header to specify which version of the API you want to use.

```bash
curl -H "X-Fanvue-API-Version: 2025-06-26" \
  -H "X-Fanvue-API-Key: your-api-key" \
  https://api.fanvue.com/users/me
```

## Error Responses

**400 Bad Request** - When requesting an unsupported version:

```json
{
  "error": "Unsupported API version",
  "message": "API version '2024-01-01' is not supported"
}
```

**410 Gone** - When requesting a sunset (removed) version:

```json
{
  "error": "API version no longer supported",
  "message": "API version '2024-01-01' was sunset on 2024-12-31T00:00:00.000Z",
  "nextVersion": "2025-06-26"
}
```

## Dive deeper

For advanced version management strategies, migration patterns, and production best practices, check out our [Version Management Strategies](/docs/advanced/version-management-strategies).


# Working With Rate Limits

# Working With Rate Limits

A rate limit is like having a bucket with a limited number of tokens. Each API request uses one token from your bucket. The bucket refills with new tokens over time, but if you use all your tokens, you'll need to wait for more to be added before making additional requests.

## How Rate Limits Work

Think of rate limiting like a water faucet with a flow regulator:

1. **Token Bucket**: You start with a full bucket of 100 request tokens
2. **Request Consumption**: Each API call uses one token from your bucket
3. **Bucket Refill**: Your bucket refills completely every 60 seconds
4. **Overflow Protection**: If your bucket is empty, you must wait for it to refill before making more requests

The system tracks your usage in real-time and provides information about your current status through response headers.

## Per-API-Key Tracking

Rate limits are tracked individually for each API key, so one application's usage doesn't affect another's limits.

## Tracking Your Usage

Every API response includes headers that tell you about your current rate limit status:

### Response Headers

**`X-RateLimit-Limit`**\
The total number of requests allowed in the current time window.

```
X-RateLimit-Limit: 100
```

**`X-RateLimit-Remaining`**\
The number of requests you have left in the current time window.

```
X-RateLimit-Remaining: 75
```

**`X-RateLimit-Reset`**\
A Unix timestamp indicating when your rate limit will reset (when your bucket refills).

```
X-RateLimit-Reset: 1672531200
```

**`Retry-After` (when rate limited)**\
When you exceed your rate limit, this header tells you how many seconds to wait before trying again.

```
Retry-After: 30
```

### Example Response Headers

Here's what you might see in a successful response:

```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1672531200
Content-Type: application/json

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com"
}
```

## When You Exceed Rate Limits

If you make too many requests and exceed your rate limit, you'll receive a `429 Too Many Requests` response:

```http
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1672531200
Retry-After: 45
Content-Type: application/json

{
  "error": "Too many requests"
}
```

This response tells you:

* You've used all 100 of your allowed requests
* You have 0 requests remaining
* Your limit will reset at timestamp 1672531200
* You should wait 45 seconds before making another request

## Working with Rate Limits In Your App

### Monitor Your Usage

Always check the rate limit headers in your responses to monitor your usage:

```javascript
const response = await fetch("https://api.fanvue.com/users/me", {
  headers: {
    "X-Fanvue-API-Key": process.env.FANVUE_API_KEY,
  },
});

const limit = response.headers.get("X-RateLimit-Limit");
const remaining = response.headers.get("X-RateLimit-Remaining");
const reset = response.headers.get("X-RateLimit-Reset");

console.log(`Rate limit: ${remaining}/${limit} requests remaining`);
console.log(`Resets at: ${new Date(parseInt(reset) * 1000)}`);
```

### Handle Rate Limit Errors

Implement proper error handling for rate limit responses:

```javascript
async function makeAPIRequest(url) {
  const response = await fetch(url, {
    headers: {
      "X-Fanvue-API-Key": process.env.FANVUE_API_KEY,
    },
  });

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After");
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);

    // Wait and retry
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return makeAPIRequest(url);
  }

  return response.json();
}
```

### Best Practices

**Implement Exponential Backoff**\
When you hit rate limits, wait progressively longer between retry attempts.

**Batch Your Requests**\
If possible, combine multiple operations into fewer API calls.

**Cache Responses**\
Store API responses locally to reduce the number of requests you need to make.

**Monitor Continuously**\
Keep track of your rate limit headers to avoid hitting limits unexpectedly.

**Plan for Peak Usage**\
Consider your application's peak usage patterns and design accordingly.

### Python Example

```python
import requests
import time
import os

def make_request_with_retry(url, max_retries=3):
    headers = {
        'X-Fanvue-API-Key': os.getenv('FANVUE_API_KEY')
    }

    for attempt in range(max_retries + 1):
        response = requests.get(url, headers=headers)

        # Check rate limit headers
        remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
        print(f"Requests remaining: {remaining}")

        if response.status_code == 429:
            if attempt < max_retries:
                retry_after = int(response.headers.get('Retry-After', 60))
                print(f"Rate limited. Waiting {retry_after} seconds...")
                time.sleep(retry_after)
                continue
            else:
                raise Exception("Max retries exceeded")

        return response.json()
```


# Version Management Strategies

# Version Management Strategies

API versioning is like having different editions of a software library. Each version represents a snapshot of the API at a specific point in time, with its own set of features, bug fixes, and behaviors. Unlike traditional software where you choose which version to install, with APIs you specify which "edition" you want to use with each request.

## How API Versioning Works

Think of API versioning like a library with multiple editions of the same book:

1. **Version Selection**: You specify which edition (version) you want to read with each request
2. **Compatibility**: Each version maintains its behavior, even as newer versions are released
3. **Deprecation**: Older editions eventually go out of print (get deprecated)
4. **Sunset**: Eventually, very old editions are removed from the library entirely

The API uses your version header to determine which set of behaviors, response formats, and business logic to apply to your request.

## Version Lifecycle Management

Every API version goes through a predictable lifecycle:

* **Active**: Current version, fully supported with new features
* **Deprecated**: Still works but marked for future removal
* **Sunset**: No longer available, returns 410 Gone

## Understanding Deprecation Headers

When you use a deprecated API version, the response includes detailed information about the deprecation timeline:

### Response Headers

**`Deprecation`**\
RFC 8594 standard header indicating when the version was officially deprecated.

```
Deprecation: Wed, 11 Nov 2024 23:59:59 GMT
```

**`Sunset`**\
RFC 8594 standard header indicating when the version will stop working.

```
Sunset: Wed, 11 Nov 2025 23:59:59 GMT
```

**`X-Fanvue-API-Next-Version`**\
Fanvue-specific header recommending which version to migrate to.

```
X-Fanvue-API-Next-Version: 2025-06-26
```

### Example Response with Deprecation

Here's what you'll see when using a deprecated version:

```http
HTTP/1.1 200 OK
Deprecation: Wed, 11 Nov 2024 23:59:59 GMT
Sunset: Wed, 11 Nov 2025 23:59:59 GMT
X-Fanvue-API-Next-Version: 2025-06-26
Content-Type: application/json

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com",
  "handle": "creator123"
}
```

This response tells you:

* The version was deprecated on November 11, 2024
* It will stop working on November 11, 2025
* You should migrate to version 2025-06-26
* Your request still works for now

## Version Error Responses

### Unsupported Version (400)

When you request a version that was never supported:

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Unsupported API version",
  "message": "API version '2024-01-01' is not supported"
}
```

### Sunset Version (410)

When you request a version that has been permanently removed:

```http
HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "API version no longer supported",
  "message": "API version '2024-01-01' was sunset on 2024-12-31T00:00:00.000Z",
  "nextVersion": "2025-06-26"
}
```

## Building Version-Aware Applications

### Version Header Management

Always include the version header in your API client configuration:

```javascript
class FanvueAPIClient {
  constructor(apiKey, version) {
    this.apiKey = apiKey;
    this.version = version;
    this.baseURL = "https://api.fanvue.com";
  }

  async request(endpoint, options = {}) {
    const response = await fetch(`${this.baseURL}${endpoint}`, {
      ...options,
      headers: {
        "X-Fanvue-API-Key": this.apiKey,
        "X-Fanvue-API-Version": this.version,
        "Content-Type": "application/json",
        ...options.headers,
      },
    });

    // Check for deprecation warnings
    this.handleDeprecationHeaders(response);

    return this.handleResponse(response);
  }

  handleDeprecationHeaders(response) {
    const deprecation = response.headers.get("Deprecation");
    const sunset = response.headers.get("Sunset");
    const nextVersion = response.headers.get("X-Fanvue-API-Next-Version");

    if (deprecation) {
      console.warn(`API version ${this.version} is deprecated as of ${deprecation}`);
      if (sunset) {
        console.warn(`Version will stop working on ${sunset}`);
      }
      if (nextVersion) {
        console.warn(`Consider upgrading to version ${nextVersion}`);
      }
    }
  }
}
```

### Version Error Handling

Implement robust error handling for version-related failures:

```javascript
async function handleResponse(response) {
  if (response.status === 400) {
    const error = await response.json();
    if (error.error === "Unsupported API version") {
      throw new UnsupportedVersionError(error.message);
    }
  }

  if (response.status === 410) {
    const error = await response.json();
    if (error.error === "API version no longer supported") {
      throw new SunsetVersionError(error.message, error.nextVersion);
    }
  }

  if (!response.ok) {
    throw new APIError(`HTTP ${response.status}: ${response.statusText}`);
  }

  return response.json();
}

class UnsupportedVersionError extends Error {
  constructor(message) {
    super(message);
    this.name = "UnsupportedVersionError";
  }
}

class SunsetVersionError extends Error {
  constructor(message, nextVersion) {
    super(message);
    this.name = "SunsetVersionError";
    this.nextVersion = nextVersion;
  }
}
```

### Python Implementation

```python
import requests
import logging
from datetime import datetime
from typing import Optional

class FanvueClient:
    def __init__(self, api_key: str, version: str):
        self.api_key = api_key
        self.version = version
        self.base_url = "https://api.fanvue.com"
        self.session = requests.Session()
        self.session.headers.update({
            'X-Fanvue-API-Key': api_key,
            'X-Fanvue-API-Version': version,
            'Content-Type': 'application/json'
        })

    def request(self, method: str, endpoint: str, **kwargs):
        response = self.session.request(method, f"{self.base_url}{endpoint}", **kwargs)

        # Monitor deprecation status
        self._check_deprecation_headers(response)

        # Handle version errors
        if response.status_code == 400:
            error_data = response.json()
            if "Unsupported API version" in error_data.get("error", ""):
                raise UnsupportedVersionError(error_data["message"])

        if response.status_code == 410:
            error_data = response.json()
            if "API version no longer supported" in error_data.get("error", ""):
                raise SunsetVersionError(
                    error_data["message"],
                    error_data.get("nextVersion")
                )

        response.raise_for_status()
        return response.json()

    def _check_deprecation_headers(self, response):
        deprecation = response.headers.get('Deprecation')
        sunset = response.headers.get('Sunset')
        next_version = response.headers.get('X-Fanvue-API-Next-Version')

        if deprecation:
            logging.warning(f"API version {self.version} deprecated as of {deprecation}")
            if sunset:
                sunset_date = datetime.strptime(sunset, '%a, %d %b %Y %H:%M:%S %Z')
                logging.warning(f"Version sunset scheduled for {sunset_date}")
            if next_version:
                logging.warning(f"Recommended migration to version {next_version}")

class UnsupportedVersionError(Exception):
    pass

class SunsetVersionError(Exception):
    def __init__(self, message: str, next_version: Optional[str] = None):
        super().__init__(message)
        self.next_version = next_version
```

## Advanced Version Management Strategies

### Version Pinning

Pin to specific versions in production to ensure predictable behavior:

```javascript
// Good: Explicit version pinning
const client = new FanvueAPIClient(apiKey, "2025-06-26");

// Avoid: Dynamic version selection in production
const client = new FanvueAPIClient(apiKey, getLatestVersion());
```

### Graceful Migration Patterns

Implement gradual migration with fallback logic:

```javascript
class VersionMigrationClient extends FanvueAPIClient {
  constructor(apiKey, primaryVersion, fallbackVersion) {
    super(apiKey, primaryVersion);
    this.fallbackVersion = fallbackVersion;
  }

  async requestWithFallback(endpoint, options = {}) {
    try {
      return await this.request(endpoint, options);
    } catch (error) {
      if (error instanceof SunsetVersionError) {
        console.warn(`Primary version sunset, falling back to ${this.fallbackVersion}`);
        // Create temporary client with fallback version
        const fallbackClient = new FanvueAPIClient(this.apiKey, this.fallbackVersion);
        return await fallbackClient.request(endpoint, options);
      }
      throw error;
    }
  }
}
```

### Monitoring and Alerting

Set up monitoring for deprecation warnings:

```javascript
class MonitoredAPIClient extends FanvueAPIClient {
  constructor(apiKey, version, metricsCollector) {
    super(apiKey, version);
    this.metrics = metricsCollector;
  }

  handleDeprecationHeaders(response) {
    const deprecation = response.headers.get("Deprecation");
    const sunset = response.headers.get("Sunset");

    if (deprecation) {
      this.metrics.increment("api.version.deprecated", {
        version: this.version,
        deprecation_date: deprecation,
        sunset_date: sunset,
      });

      // Alert if sunset is approaching
      if (sunset) {
        const sunsetDate = new Date(sunset);
        const daysUntilSunset = (sunsetDate - new Date()) / (1000 * 60 * 60 * 24);

        if (daysUntilSunset <= 30) {
          this.metrics.alert("api.version.sunset_approaching", {
            version: this.version,
            days_remaining: Math.floor(daysUntilSunset),
          });
        }
      }
    }
  }
}
```

## Best Practices for Production

### Configuration Management

* Store API versions in environment variables or configuration files
* Use the same version across all environments (dev, staging, production)
* Document which version each deployment uses

### Testing Strategy

* Test version migration in staging environments first
* Implement integration tests for each supported API version
* Validate that deprecated versions still work as expected

### Deployment Planning

* Plan version migrations during maintenance windows
* Implement feature flags for gradual version rollouts
* Monitor error rates closely after version changes

### Team Coordination

* Establish clear policies for when to upgrade API versions
* Create alerts for deprecation warnings in production
* Document migration procedures for your team


# Docs For Your LLM

# Docs for LLMs

Our API documentation is available in text formats optimized for Large Language Models.

## Endpoints

**Standard:** [http://api.fanvue.com/docs/llms.txt](http://api.fanvue.com/docs/llms.txt)

**Full:** [http://api.fanvue.com/docs/llms-full.txt](http://api.fanvue.com/docs/llms-full.txt)

Use these URLs to provide your LLM with current API information.


# Get current user

GET https://api.fanvue.com/users/me

Get details of the currently authenticated user.

    <Info>Scope required: `read:self`</Info>

Reference: https://api.fanvue.com/docs/reference/users/get-current-user

## Examples

```shell
curl https://api.fanvue.com/users/me \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl https://api.fanvue.com/users/me \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl https://api.fanvue.com/users/me \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl https://api.fanvue.com/users/me \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl https://api.fanvue.com/users/me \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

# Get list of chats

GET https://api.fanvue.com/chats

Returns a paginated list of chat conversations. Use 'page' to navigate through results and 'size' to control how many chats are returned per page.

    <Info>Scope required: `read:chat`</Info>

Reference: https://api.fanvue.com/docs/reference/chats/list-chats

## Examples

```shell
curl https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Create a new chat

POST https://api.fanvue.com/chats
Content-Type: application/json

Create a new chat conversation with a user.

<Info>Scope required: `write:chat`</Info>

Reference: https://api.fanvue.com/docs/reference/chats/create-chat

## Examples

```shell
curl -X POST https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "foo"
}'
```

```shell
curl -X POST https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

# Send a message

POST https://api.fanvue.com/chats/{userUuid}/message
Content-Type: application/json

Send a text message to a user in an existing chat conversation.

    <Info>Scope required: `write:chat`</Info>

Reference: https://api.fanvue.com/docs/reference/chats/send-message

## Examples

```shell
curl -X POST https://api.fanvue.com/chats/userUuid/message \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "foo"
}'
```

```shell
curl -X POST https://api.fanvue.com/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

# Get messages from a chat

GET https://api.fanvue.com/chats/{userUuid}/messages

Returns a paginated list of text messages between the authenticated user and the specified user. Messages are ordered by creation date (newest first).

    <Info>Scope required: `read:chat`</Info>

Reference: https://api.fanvue.com/docs/reference/chats/list-messages

## Examples

```shell
curl https://api.fanvue.com/chats/userUuid/messages \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Get followers

GET https://api.fanvue.com/followers

Returns a paginated list of users who follow the authenticated user, excluding those with active subscriptions to avoid duplication.

    <Info>Scope required: `read:fan`</Info>

Reference: https://api.fanvue.com/docs/reference/creators/list-followers

## Examples

```shell
curl https://api.fanvue.com/followers \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Get subscribers

GET https://api.fanvue.com/subscribers

Returns a paginated list of users who have subscriptions to the authenticated user.

    <Info>Scope required: `read:fan`</Info>

Reference: https://api.fanvue.com/docs/reference/creators/list-subscribers

## Examples

```shell
curl https://api.fanvue.com/subscribers \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Get earnings data

GET https://api.fanvue.com/insights/earnings

Returns cursor-paginated invoice data for the authenticated creator over a specified time period.

<Info>Scope required: `read:insights`</Info>

Reference: https://api.fanvue.com/docs/reference/insights/get-earnings

## Examples

```shell
curl https://api.fanvue.com/insights/earnings \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

# Get top-spending fans

GET https://api.fanvue.com/insights/top-spenders

Returns a paginated list of the top-spending fans for the authenticated creator with their spending totals and message counts.

<Info>Scopes required: `read:insights`, `read:fan`</Info>

Reference: https://api.fanvue.com/docs/reference/insights/get-top-spenders

## Examples

```shell
curl https://api.fanvue.com/insights/top-spenders \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

# Get subscribers count

GET https://api.fanvue.com/insights/subscribers

Returns cursor-paginated subscribers count for the authenticated creator over a specified time period.

Data is aggregated daily with timezone-aware boundaries. When dates include timezone offsets, results are normalized to midnight in that timezone (expressed as UTC). 

<Info>Scope required: `read:insights`</Info>

Reference: https://api.fanvue.com/docs/reference/insights/get-subscribers

## Examples

```shell
curl https://api.fanvue.com/insights/subscribers \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

# Get agency creators

GET https://api.fanvue.com/creators

Returns a paginated list of creators associated with the authenticated agency user's organization.

    <Info>Scope required: `read:creator`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/list-creators

## Examples

```shell
curl https://api.fanvue.com/creators \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/creators \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Get creator followers

GET https://api.fanvue.com/creators/{creatorUserUuid}/followers

Returns a paginated list of users who follow the specified creator.

    <Info>Scopes required: `read:creator`, `read:fan`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/list-creator-followers

## Examples

```shell
curl https://api.fanvue.com/creators/creatorUserUuid/followers \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/followers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Get creator subscribers

GET https://api.fanvue.com/creators/{creatorUserUuid}/subscribers

Returns a paginated list of users subscribed to the specified creator.

    <Info>Scopes required: `read:creator`, `read:fan`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/list-creator-subscribers

## Examples

```shell
curl https://api.fanvue.com/creators/creatorUserUuid/subscribers \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Get chats of a creator

GET https://api.fanvue.com/creators/{creatorUserUuid}/chats

Returns a paginated list of chats for the specified creator.

    <Info>Scopes required: `read:creator`, `read:chat`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/list-creator-chats

## Examples

```shell
curl https://api.fanvue.com/creators/creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Create new chat as creator

POST https://api.fanvue.com/creators/{creatorUserUuid}/chats
Content-Type: application/json

Create a new chat conversation as a creator.

    <Info>Scopes required: `write:chat`, `read:creator`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/create-creator-chat

## Examples

```shell
curl -X POST https://api.fanvue.com/creators/creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "foo"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userUuid": "string"
}'
```

# Send a message as creator

POST https://api.fanvue.com/creators/{creatorUserUuid}/chats/{userUuid}/message
Content-Type: application/json

Send a text message as a creator in an existing chat conversation.

    <Info>Scopes required: `write:chat`, `read:creator`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/send-creator-message

## Examples

```shell
curl -X POST https://api.fanvue.com/creators/creatorUserUuid/chats/userUuid/message \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "foo"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

```shell
curl -X POST https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/message \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "string"
}'
```

# Get messages between a creator and a user

GET https://api.fanvue.com/creators/{creatorUserUuid}/chats/{userUuid}/messages

Returns a paginated list of text messages between the specified creator and user. Messages are ordered by creation date (newest first).

    <Info>Scopes required: `read:creator`, `read:chat`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/list-creator-messages

## Examples

```shell
curl https://api.fanvue.com/creators/creatorUserUuid/chats/userUuid/messages \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/chats/:userUuid/messages \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d page=1 \
     -d size=1
```

# Get earnings data for a creator

GET https://api.fanvue.com/creators/{creatorUserUuid}/insights/earnings

Returns cursor-paginated invoice data for the specified creator over a specified time period.

<Info>Scopes required: `read:creator`, `read:insights`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/get-creator-earnings

## Examples

```shell
curl https://api.fanvue.com/creators/creatorUserUuid/insights/earnings \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/earnings \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

# Get top-spending fans for a creator

GET https://api.fanvue.com/creators/{creatorUserUuid}/insights/top-spenders

Returns a paginated list of the top-spending fans for the specified creator with their spending totals and message counts.

<Info>Scopes required: `read:creator`, `read:insights`, `read:fan`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/get-creator-top-spenders

## Examples

```shell
curl https://api.fanvue.com/creators/creatorUserUuid/insights/top-spenders \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/top-spenders \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

# Get subscribers count for a creator

GET https://api.fanvue.com/creators/{creatorUserUuid}/insights/subscribers

Returns cursor-paginated subscribers count for the specified creator over a specified time period.

Data is aggregated daily with timezone-aware boundaries. When dates include timezone offsets, results are normalized to midnight in that timezone (expressed as UTC).

<Info>Scopes required: `read:creator`, `read:insights`</Info>

Reference: https://api.fanvue.com/docs/reference/agencies/get-creator-subscribers

## Examples

```shell
curl https://api.fanvue.com/creators/creatorUserUuid/insights/subscribers \
     -H "X-Fanvue-API-Version: 2025-06-26" \
     -H "X-Fanvue-API-Key: <apiKey>"
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```

```shell
curl -G https://api.fanvue.com/creators/:creatorUserUuid/insights/subscribers \
     -H "X-Fanvue-API-Version: string" \
     -H "X-Fanvue-API-Key: <apiKey>" \
     -d startDate=string \
     -d endDate=string
```