{"openapi":"3.1.0","info":{"title":"Fanvue API","version":"0.1"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"ApiVersionHeader":{"name":"X-Fanvue-API-Version","in":"header","required":true,"schema":{"type":"string","default":"2025-06-26","example":"2025-06-26"},"description":"API version to use for the request"}},"responses":{"UnauthorizedResponse":{"description":"Unauthorized Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"NotFoundResponse":{"description":"Not Found Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnsupportedVersionResponse":{"description":"API version not supported","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"SunsetVersionResponse":{"description":"API version no longer supported (sunset)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"nextVersion":{"type":"string"}},"required":["error","message"]}}}},"ValidationErrorResponse":{"description":"Request validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of validation errors"}},"required":["errors"]}}}},"ContactabilityErrorResponse":{"description":"User contactability validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error message explaining why the user is not contactable"}},"required":["message"]}}}},"InvalidUuidErrorResponse":{"description":"Invalid UUID format provided","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error message indicating which UUID parameter is invalid"}},"required":["message"]}}}},"RateLimitResponse":{"description":"Too many requests - rate limit exceeded","headers":{"Retry-After":{"description":"Number of seconds to wait before retrying the request","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The maximum number of requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"The Unix timestamp (seconds) when the rate limit window resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"schemas":{"UnsupportedVersionError":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"description":"API version not supported"},"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}},"required":["errors"],"description":"Request validation failed"},"ContactabilityError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"description":"User contactability validation failed"},"InvalidUuidError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"description":"Invalid UUID format provided"},"MessageValidationError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"description":"Message validation failed (media ownership, content validation, etc.)"},"EarningSource":{"type":"string","enum":["all","affiliate","appStore","mediaLink","message","post","referral","renewal","subscription","tip","giveaway"]},"SpendingType":{"type":"string","enum":["all","refund","chargeback"],"description":"The spending type filter"},"SpendingSource":{"type":"string","enum":["refund","chargeback"]},"MediaVariantType":{"type":"string","enum":["blurred","main","thumbnail","thumbnail_gallery"],"description":"The type of media variant"},"MediaStatus":{"type":"string","enum":["created","processing","ready","error"],"description":"The status of media"},"PostAudience":{"type":"string","enum":["subscribers","followers-and-subscribers"],"description":"Audience that can view the post"},"ExternalSocialPlatform":{"type":"string","enum":["facebook","instagram","other","reddit","snapchat","tiktok","twitter","youtube"],"description":"The external social platform"}}},"paths":{"/agencies/team-members":{"get":{"summary":"List team members","description":"Get a list of all team members in the authenticated user's agency.\n\n<Info>Scope required: `read:agency`</Info>\n<Info>Requires: Agency admin access</Info>","operationId":"listTeamMembers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"List of team members","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"isAdmin":{"type":"boolean"},"nickname":{"type":"string","nullable":true},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"creatorAccess":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["ADMIN","CHATTER"]}},"required":["uuid","role"]}}},"required":["uuid","isAdmin","nickname","email","displayName","creatorAccess"]}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/agencies/team-members/{userId}":{"put":{"summary":"Update team member","description":"Update a team member's properties such as admin status or nickname.\n\n<Info>Scope required: `write:agency`</Info>\n<Info>Requires: Agency admin access</Info>","operationId":"updateTeamMember","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Team member user UUID"},"required":true,"description":"Team member user UUID","name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","nullable":true,"description":"Nickname for the team member"},"creatorUuids":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Array of creator UUIDs that this team member should have access to"}},"required":["creatorUuids"]}}}},"responses":{"200":{"description":"Team member updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"isAdmin":{"type":"boolean"},"nickname":{"type":"string","nullable":true},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"creatorAccess":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["ADMIN","CHATTER"]}},"required":["uuid","role"]}}},"required":["uuid","isAdmin","nickname","email","displayName","creatorAccess"]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/agencies/invites":{"post":{"summary":"Invite a team member","description":"Invite a new team member to the authenticated user's agency by email.\n\nThe invited user must have an existing account, must not be a creator, and must not already be invited to this agency.\n\n<Info>Scope required: `write:agency`</Info>\n<Info>Requires: Agency admin access</Info>","operationId":"createAgencyInvite","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the user to invite"}},"required":["email"]}}}},"responses":{"200":{"description":"Team member invited successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"inviteUuid":{"type":"string","format":"uuid"}},"required":["success","message","inviteUuid"]},"example":{"success":true,"message":"Invitation sent successfully.","inviteUuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/agencies/creator-invites":{"post":{"summary":"Invite a creator","description":"Invite a creator to connect to the authenticated user's agency by email.\n\nThe invited user must have an existing Fanvue creator account. An email will be sent to the creator with a link to accept the invitation. The creator does not need to share their password.\n\n<Info>Scope required: `write:agency`</Info>\n<Info>Requires: Agency admin access</Info>","operationId":"createCreatorInvite","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the creator to invite"}},"required":["email"]}}}},"responses":{"200":{"description":"Creator invitation sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]},"example":{"success":true,"message":"Creator invitation sent successfully."}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/agencies/insights/chatter-leaderboard":{"get":{"summary":"Get chatter leaderboard","description":"Returns per-chatter performance metrics for the authenticated user's agency over a specified time period.\n\nEach row includes message volume, PPV sends and unlocks, revenue, derived ratios (golden ratio, unlock ratio), active hours, earnings per active hour, and average response time. Rows are sorted by revenue descending.\n\nStats are sourced from the daily aggregation table and are refreshed at most once per day, so very recent activity may not be reflected.\n\n<Info>Scope required: `read:agency`</Info>\n<Info>Requires: Agency admin access</Info>","operationId":"getChatterLeaderboard","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Stats are aggregated by UTC day."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Stats are aggregated by UTC day.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Stats are aggregated by UTC day."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Stats are aggregated by UTC day.","name":"endDate","in":"query"},{"schema":{"type":"string","description":"Comma-separated chatter UUIDs to filter by (max 100). Defaults to all chatters in the agency."},"required":false,"description":"Comma-separated chatter UUIDs to filter by (max 100). Defaults to all chatters in the agency.","name":"chatterUuids","in":"query"}],"responses":{"200":{"description":"Chatter leaderboard data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"chatterUuid":{"type":"string","format":"uuid","description":"UUID of the chatter (agency team member)"},"chatterName":{"type":"string","description":"Chatter's nickname within the agency, falling back to display name"},"avatarUrl":{"type":"string","nullable":true,"description":"URL of the chatter's avatar image, or null"},"messages":{"type":"integer","description":"Total messages sent in the period"},"ppvsSent":{"type":"integer","description":"Total pay-per-view messages sent in the period"},"ppvsUnlocked":{"type":"integer","description":"Total pay-per-view messages unlocked by fans in the period"},"revenue":{"type":"integer","description":"Total revenue from PPV unlocks in the period, in cents"},"goldenRatio":{"type":"number","description":"Ratio of PPVs unlocked to messages sent (0 if no messages were sent)"},"unlockRatio":{"type":"number","description":"Ratio of PPVs unlocked to PPVs sent (0 if no PPVs were sent)"},"activeHours":{"type":"number","description":"Number of hours the chatter was active in the period"},"eph":{"type":"number","description":"Earnings per active hour, in cents (0 if no active hours)"},"avgResponseMs":{"type":"number","nullable":true,"description":"Average response time in milliseconds, or null if no responses were tracked"}},"required":["chatterUuid","chatterName","avatarUrl","messages","ppvsSent","ppvsUnlocked","revenue","goldenRatio","unlockRatio","activeHours","eph","avgResponseMs"]}}},"required":["data"]},"example":{"data":[{"chatterUuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","chatterName":"Top Performer","avatarUrl":"https://cdn.example.com/avatars/a1b2c3d4.jpg","messages":1240,"ppvsSent":86,"ppvsUnlocked":41,"revenue":124500,"goldenRatio":0.033,"unlockRatio":0.477,"activeHours":38.5,"eph":3233,"avgResponseMs":45200},{"chatterUuid":"b2c3d4e5-f6a7-8901-bcde-f12345678901","chatterName":"Rookie","avatarUrl":null,"messages":320,"ppvsSent":12,"ppvsUnlocked":3,"revenue":6000,"goldenRatio":0.009,"unlockRatio":0.25,"activeHours":8,"eph":750,"avgResponseMs":null}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/agencies/chats":{"get":{"summary":"List chats across all agency creators","description":"Returns a single paginated stream of chats across every creator the authenticated agency manages, sorted by most recent activity. Each row is tagged with `creatorUuid` so consumers can group results by creator without an additional join.\n\nReplaces the per-creator `GET /creators/{uuid}/chats` fan-out used by agency CRM sync flows: 1 + N calls collapse to ceil(total/size) calls.\n\nMute state is per-creator: `isMuted` is true only when the specific creator that owns the chat row has muted the counterpart, not when any other agency creator has.\n\n<Info>Scopes required: `read:agency`, `read:chat`</Info>\n<Info>Requires: Agency admin access</Info>","operationId":"listAgencyChats","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"Paginated list of chats across the agency's creators","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":"string","nullable":true,"format":"date"},"lastMessageAt":{"type":"string","nullable":true,"format":"date","description":"Date of the last message in this chat"},"isRead":{"type":"boolean","description":"Whether the chat is marked as read (true) or unread (false)"},"isMuted":{"type":"boolean"},"unreadMessagesCount":{"type":"number"},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"lastMessage":{"type":"object","nullable":true,"properties":{"text":{"type":"string","nullable":true},"type":{"type":"string","enum":["AUTOMATED_CANCELED","AUTOMATED_NEW_FOLLOWER","AUTOMATED_NEW_PURCHASE","AUTOMATED_NEW_SUBSCRIBER","AUTOMATED_RE_SUBSCRIBED","AUTOMATED_RENEWED","AUTOMATED_CHAT_MESSAGE_REPLY","AUTOMATED_FIRST_MESSAGE_REPLY","CHAT_TEXT_GENERATION","CHAT_TEXT_REPLY","CHAT_TEXT_REWRITE","SINGLE_RECIPIENT","TIP","VOICE_CALL","BROADCAST","GHOST_PROMOTION"]},"uuid":{"type":"string"},"sentAt":{"type":"string","nullable":true,"format":"date"},"hasMedia":{"type":"boolean","nullable":true},"mediaType":{"type":"string","nullable":true,"enum":["image","video","audio","document"]},"senderUuid":{"type":"string","format":"uuid"},"sentByUserId":{"type":"string","nullable":true,"format":"uuid","description":"UUID of the team member who sent the message on behalf of the creator, or null if sent directly by the creator"}},"required":["text","type","uuid","sentAt","hasMedia","mediaType","senderUuid","sentByUserId"]},"creatorUuid":{"type":"string","format":"uuid","description":"UUID of the agency-managed creator that owns this chat"}},"required":["createdAt","lastMessageAt","isRead","isMuted","unreadMessagesCount","user","lastMessage","creatorUuid"]},"description":"Array of chats across the agency's creators"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"createdAt":"2024-01-15T00:00:00.000Z","lastMessageAt":"2024-01-15T00:00:00.000Z","isRead":false,"isMuted":false,"unreadMessagesCount":3,"creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"lastMessage":{"uuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","text":"Hey there! How are you doing?","type":"SINGLE_RECIPIENT","sentAt":"2024-01-15T00:00:00.000Z","hasMedia":true,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","sentByUserId":null}},{"createdAt":"2024-01-14T00:00:00.000Z","lastMessageAt":"2024-01-15T00:00:00.000Z","isRead":true,"isMuted":false,"unreadMessagesCount":0,"creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r9","user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"lastMessage":null}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/apps/{appUuid}/subscription-status":{"get":{"summary":"Get app pricing subscription lifecycle status","description":"Returns pricing plan lifecycle states for a developer-owned app (`pending_setup`, `active`, `withdrawn`).\n\n    <Info>Scope required: `read:self`</Info>","operationId":"getAppSubscriptionStatus","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"}],"responses":{"200":{"description":"Pricing plan lifecycle summary for the app","content":{"application/json":{"schema":{"type":"object","properties":{"appUuid":{"type":"string","format":"uuid"},"appName":{"type":"string"},"availability":{"type":"string","enum":["complete","horizonUnavailable"]},"overallStatus":{"type":"string","enum":["notConfigured","pendingSetup","active","withdrawn","mixed","unavailable"]},"pricingPlans":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string"},"billingType":{"type":"string","enum":["free","one_time","recurring"]},"interval":{"type":"string","nullable":true,"enum":["monthly","yearly"]},"price":{"type":"number"},"currencyCode":{"type":"string"},"status":{"type":"string","enum":["pending_setup","active","withdrawn"]}},"required":["uuid","name","billingType","interval","price","currencyCode","status"]}}},"required":["appUuid","appName","availability","overallStatus","pricingPlans"]},"example":{"appUuid":"00000000-0000-4000-8000-000000000001","appName":"Example App","availability":"complete","overallStatus":"pendingSetup","pricingPlans":[{"uuid":"00000000-0000-4000-8000-000000000002","name":"Monthly","billingType":"recurring","interval":"monthly","price":999,"currencyCode":"USD","status":"pending_setup"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"App not found or not owned by the authenticated user","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"},"502":{"description":"Failed to load subscription status from upstream","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"503":{"description":"Developer API upstream is not configured","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/apps/{appUuid}/subscription/me":{"get":{"summary":"Get current user subscription for an installed app","description":"Returns paid entitlement for the authenticated user for the app identified by `appUuid`. The OAuth access token must belong to that app.\n\n    When the authenticated user is an agency team member, the response also includes a `managedCreators` array containing the subscription state for every creator the team member is assigned to. The agency user's own top-level subscription will be `status: \"none\"` (agency team members do not install apps themselves). For non-agency users `managedCreators` is an empty array.\n\n    <Info>Scope required: `read:self`</Info>","operationId":"getAppCurrentUserSubscription","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"}],"responses":{"200":{"description":"Current-user subscription entitlement for the app","content":{"application/json":{"schema":{"type":"object","properties":{"appUuid":{"type":"string","format":"uuid"},"userUuid":{"type":"string","format":"uuid"},"hasActiveSubscription":{"type":"boolean"},"status":{"type":"string","enum":["active","pending","cancelled","none"]},"planUuid":{"type":"string","nullable":true,"format":"uuid"},"planName":{"type":"string","nullable":true},"currentPeriodEnd":{"type":"string","nullable":true},"cancelAtPeriodEnd":{"type":"boolean"},"managedCreators":{"type":"array","items":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid"},"hasActiveSubscription":{"type":"boolean"},"status":{"type":"string","enum":["active","pending","cancelled","none"]},"planUuid":{"type":"string","nullable":true,"format":"uuid"},"planName":{"type":"string","nullable":true},"currentPeriodEnd":{"type":"string","nullable":true},"cancelAtPeriodEnd":{"type":"boolean"}},"required":["userUuid","hasActiveSubscription","status","planUuid","planName","currentPeriodEnd","cancelAtPeriodEnd"]}}},"required":["appUuid","userUuid","hasActiveSubscription","status","planUuid","planName","currentPeriodEnd","cancelAtPeriodEnd","managedCreators"]},"example":{"appUuid":"00000000-0000-4000-8000-000000000001","userUuid":"00000000-0000-4000-8000-000000000003","hasActiveSubscription":true,"status":"active","planUuid":"00000000-0000-4000-8000-000000000002","planName":"Pro Monthly","currentPeriodEnd":"2026-05-01T00:00:00.000Z","cancelAtPeriodEnd":false,"managedCreators":[{"userUuid":"00000000-0000-4000-8000-000000000004","hasActiveSubscription":true,"status":"active","planUuid":"00000000-0000-4000-8000-000000000002","planName":"Pro Monthly","currentPeriodEnd":"2026-05-01T00:00:00.000Z","cancelAtPeriodEnd":false}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"App not found for this user","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"},"502":{"description":"Failed to load subscription from upstream","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"503":{"description":"Developer API upstream is not configured","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/chats":{"post":{"summary":"Create a new chat","description":"Create a new chat conversation with a user.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"createChat","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid"}},"required":["userUuid"]}}}},"responses":{"201":{"description":"Chat created","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Chat created successfully"}}}},"400":{"description":"Bad Request - API version not supported OR user contactability validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ContactabilityError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"get":{"summary":"Get list of chats","description":"Returns a paginated list of chat conversations with optional filtering, searching, and sorting.\n\n**Available Filters** (via `filter` parameter):\n- `unread` - Only unread chats\n- `online` - Only online users\n- `subscribed_to` - Users you're subscribed to\n- `not_muted` - Exclude muted chats\n- `subscribers` - Only subscribers (creator-only)\n- `followers` - Only followers (creator-only)\n- `recent_subscribers` - Recently subscribed (creator-only)\n- `not_answered` - Unanswered chats (creator-only)\n- `spent_more_than_50` - High spenders (creator-only)\n- `on_free_trial` - Free trial users (creator-only)\n- `has_tipped` - Users who have tipped (creator-only)\n- `spenders` - All spenders (creator-only)\n- `exclude_creators` - Exclude creator accounts (creator-only)\n\n**Sort Options** (via `sortBy` parameter):\n- `most_recent_messages` (default) - Sort by most recent message\n- `online_now` - Prioritize online users\n- `most_unanswered_chats` - Sort by unanswered count\n\n<Info>Scope required: `read:chat`</Info>\n\n<Warning>Some filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.</Warning>","operationId":"listChats","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter chats by custom list UUID"},"required":false,"description":"Filter chats by custom list UUID","name":"customListId","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]},"description":"Filter chats by smart list type(s)"},"required":false,"description":"Filter chats by smart list type(s)","name":"smartListIds","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["unread","subscribers","followers","online","recent_subscribers","not_answered","spent_more_than_50","on_free_trial","has_tipped","spenders","exclude_creators","subscribed_to","not_muted","archived"]},"description":"Filter types to apply (can specify multiple via repeated params)"},"required":false,"description":"Filter types to apply (can specify multiple via repeated params)","name":"filter","in":"query"},{"schema":{"type":"string","maxLength":100,"description":"Search term to filter chats by user name/handle"},"required":false,"description":"Search term to filter chats by user name/handle","name":"search","in":"query"},{"schema":{"type":"string","enum":["most_recent_messages","online_now","most_unanswered_chats"],"description":"Sort order for chat list (default: most_recent_messages)"},"required":false,"description":"Sort order for chat list (default: most_recent_messages)","name":"sortBy","in":"query"}],"responses":{"200":{"description":"List of chats","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":"string","nullable":true,"format":"date"},"lastMessageAt":{"type":"string","nullable":true,"format":"date","description":"Date of the last message in this chat"},"isRead":{"type":"boolean","description":"Whether the chat is marked as read (true) or unread (false)"},"isMuted":{"type":"boolean"},"unreadMessagesCount":{"type":"number"},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"lastMessage":{"type":"object","nullable":true,"properties":{"text":{"type":"string","nullable":true},"type":{"type":"string","enum":["AUTOMATED_CANCELED","AUTOMATED_NEW_FOLLOWER","AUTOMATED_NEW_PURCHASE","AUTOMATED_NEW_SUBSCRIBER","AUTOMATED_RE_SUBSCRIBED","AUTOMATED_RENEWED","AUTOMATED_CHAT_MESSAGE_REPLY","AUTOMATED_FIRST_MESSAGE_REPLY","CHAT_TEXT_GENERATION","CHAT_TEXT_REPLY","CHAT_TEXT_REWRITE","SINGLE_RECIPIENT","TIP","VOICE_CALL","BROADCAST","GHOST_PROMOTION"]},"uuid":{"type":"string"},"sentAt":{"type":"string","nullable":true,"format":"date"},"hasMedia":{"type":"boolean","nullable":true},"mediaType":{"type":"string","nullable":true,"enum":["image","video","audio","document"]},"senderUuid":{"type":"string","format":"uuid"},"sentByUserId":{"type":"string","nullable":true,"format":"uuid","description":"UUID of the team member who sent the message on behalf of the creator, or null if sent directly by the creator"}},"required":["text","type","uuid","sentAt","hasMedia","mediaType","senderUuid","sentByUserId"]}},"required":["createdAt","lastMessageAt","isRead","isMuted","unreadMessagesCount","user","lastMessage"]},"description":"Array of chat conversations"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"createdAt":"2024-01-15T00:00:00.000Z","lastMessageAt":"2024-01-15T00:00:00.000Z","isRead":false,"isMuted":false,"unreadMessagesCount":3,"user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"lastMessage":{"uuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","text":"Hey there! How are you doing?","type":"SINGLE_RECIPIENT","sentAt":"2024-01-15T00:00:00.000Z","hasMedia":true,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","sentByUserId":null}},{"createdAt":"2024-01-14T00:00:00.000Z","lastMessageAt":null,"isRead":true,"isMuted":true,"unreadMessagesCount":0,"user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"lastMessage":null},{"createdAt":"2024-01-15T00:00:00.000Z","lastMessageAt":"2024-01-15T00:00:00.000Z","isRead":true,"isMuted":false,"unreadMessagesCount":0,"user":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","handle":"johnny-doey","nickname":"JohnnyD","displayName":"Johnny Doey","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"lastMessage":{"uuid":"c3d4e5f6-7890-1234-5678-9abcdef01234","text":"Check out my new post!","type":"BROADCAST","sentAt":"2024-01-15T00:00:00.000Z","hasMedia":true,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","sentByUserId":null}}],"pagination":{"page":1,"size":2,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/{userUuid}/message":{"post":{"summary":"Send a message","description":"Send a message to a user in an existing chat conversation. The message can include text, media attachments, and optional pricing for pay-to-view content.\n\n    <Info>Scope required: `write:chat`</Info>","operationId":"sendMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","nullable":true,"minLength":1,"maxLength":5000},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"}},"price":{"type":"number","nullable":true,"minimum":300},"templateUuid":{"type":"string","nullable":true,"format":"uuid"}}}}}},"responses":{"201":{"description":"Message sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"messageUuid":{"type":"string","format":"uuid"}},"required":["messageUuid"]},"example":{"messageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"}}}},"400":{"description":"Bad Request - API version not supported OR user contactability validation failed OR message validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ContactabilityError"},{"$ref":"#/components/schemas/MessageValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/{userUuid}/messages":{"get":{"summary":"Get messages from a chat","description":"Returns a paginated list of text messages between the authenticated user and the specified user. Messages are ordered by creation date (newest first).\n\n    <Info>Scope required: `read:chat`</Info>","operationId":"listMessages","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to mark the chat as read after retrieving messages"},"required":false,"description":"Whether to mark the chat as read after retrieving messages","name":"markAsRead","in":"query"}],"responses":{"200":{"description":"List of messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"text":{"type":"string","nullable":true},"sentAt":{"type":"string","nullable":true,"format":"date"},"sender":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"}},"required":["uuid","handle"]},"recipient":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"}}},"hasMedia":{"type":"boolean","nullable":true},"mediaType":{"type":"string","nullable":true,"enum":["image","video","audio","document"]},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ordered list of media UUIDs attached to this message (display order)"},"type":{"type":"string","enum":["AUTOMATED_CANCELED","AUTOMATED_NEW_FOLLOWER","AUTOMATED_NEW_PURCHASE","AUTOMATED_NEW_SUBSCRIBER","AUTOMATED_RE_SUBSCRIBED","AUTOMATED_RENEWED","AUTOMATED_CHAT_MESSAGE_REPLY","AUTOMATED_FIRST_MESSAGE_REPLY","CHAT_TEXT_GENERATION","CHAT_TEXT_REPLY","CHAT_TEXT_REWRITE","SINGLE_RECIPIENT","TIP","VOICE_CALL"]},"pricing":{"type":"object","nullable":true,"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Pricing information for pay-to-view messages"},"purchasedAt":{"type":"string","nullable":true,"format":"date","description":"Timestamp when this message was purchased, or null if not purchased"},"sentByUserId":{"type":"string","nullable":true,"format":"uuid","description":"UUID of the team member who sent the message on behalf of the creator, or null if sent directly by the creator"},"isRead":{"type":"boolean","description":"Whether the message has been read by the recipient"}},"required":["uuid","text","sentAt","sender","recipient","hasMedia","mediaType","mediaUuids","type","pricing","purchasedAt","sentByUserId","isRead"]},"description":"Array of messages in the conversation"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","text":"Hey there! How are you doing?","sentAt":"2024-01-15T00:00:00.000Z","sender":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"recipient":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","handle":"johnny-doey","nickname":"JohnnyD","displayName":"Johnny Doey","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"type":"SINGLE_RECIPIENT","hasMedia":false,"mediaType":null,"mediaUuids":[],"pricing":null,"purchasedAt":null,"sentByUserId":null},{"uuid":"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","text":"I'm doing great! Thanks for asking.","sentAt":"2024-01-15T00:00:00.000Z","sender":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","handle":"johnny-doey","nickname":"JohnnyD","displayName":"Johnny Doey","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"recipient":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"type":"SINGLE_RECIPIENT","hasMedia":true,"mediaType":"image","mediaUuids":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"pricing":{"USD":{"price":500}},"purchasedAt":"2024-01-15T00:00:00.000Z","sentByUserId":null}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"No conversation found with the given user","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/{userUuid}":{"patch":{"summary":"Update chat properties","description":"Update properties of a chat conversation with a user, such as read status, mute status, or nickname.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"updateChat","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isRead":{"type":"boolean","description":"Whether the chat should be marked as read (true) or unread (false)"},"isMuted":{"type":"boolean","description":"Whether the chat should be muted (true) or unmuted (false)"},"nickname":{"type":"string","maxLength":30,"description":"Custom nickname for the chat counterpart (max 30 characters)"}}}}}},"responses":{"204":{"description":"Chat updated successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/mass-messages":{"post":{"summary":"Send a mass message","description":"Send a message to multiple users based on selected lists.  \nIf `scheduledAt` (or alias `scheduled_at`) is provided, the message is queued for scheduled delivery instead of being sent immediately.\n\n<Info>Scope required: `write:chat` `read:fan'</Info>","operationId":"sendMassMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":5000},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"}},"price":{"type":"number","nullable":true,"minimum":300},"includedLists":{"type":"object","properties":{"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]}},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"excludedLists":{"type":"object","properties":{"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]}},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"scheduledAt":{"type":"string","format":"date-time","description":"Optional scheduled date/time in ISO 8601 format. Alias `scheduled_at` is also accepted."}},"required":["includedLists"]}}}},"responses":{"201":{"description":"Mass message sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"recipientCount":{"type":"number"},"createdAt":{"type":"string","nullable":true,"format":"date"}},"required":["id","recipientCount","createdAt"]},"example":{"id":"f1e2d3c4-b5a6-9788-c0d1-e2f3g4h5i6j7","recipientCount":1250,"createdAt":"2024-01-15T00:00:00.000Z"}}}},"400":{"description":"Bad Request - API version not supported OR user contactability validation failed OR message validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ContactabilityError"},{"$ref":"#/components/schemas/MessageValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"get":{"summary":"List mass messages","description":"Returns a paginated list of mass (broadcast) messages sent by the authenticated creator, including delivery and engagement statistics.\n\nEach item includes recipient count, view count, purchase count, and total revenue generated.\n\nUse the `includeDeleted` query parameter to also retrieve deleted (unsent) mass messages. Deleted messages will have a status of `UNSENT`.\n\n<Info>Scope required: `read:chat`</Info>\n\n<Warning>This endpoint is only available to creators.</Warning>","operationId":"listMassMessages","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Whether to include deleted (unsent) mass messages in the results. Defaults to false."},"required":false,"description":"Whether to include deleted (unsent) mass messages in the results. Defaults to false.","name":"includeDeleted","in":"query"}],"responses":{"200":{"description":"List of mass messages with statistics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"text":{"type":"string","nullable":true},"status":{"type":"string","enum":["SENT","UNSENT","SENDING","FAILED","MODERATED","SCHEDULED"],"description":"Current status of the mass message"},"price":{"type":"number","nullable":true,"description":"Price in cents for pay-to-view content, or null if free"},"createdAt":{"type":"string","nullable":true,"format":"date"},"publishedAt":{"type":"string","nullable":true,"format":"date","description":"When the message was published/sent"},"recipientCount":{"type":"number","description":"Number of recipients the message was sent to"},"viewCount":{"type":"number","description":"Number of recipients who have viewed the message"},"purchaseCount":{"type":"number","description":"Number of recipients who purchased the pay-to-view content"},"totalRevenue":{"type":"number","description":"Total revenue generated from purchases of this message (in cents)"}},"required":["uuid","text","status","price","createdAt","publishedAt","recipientCount","viewCount","purchaseCount","totalRevenue"]},"description":"Array of mass messages with delivery and engagement statistics"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90","text":"Hey everyone! Check out my new exclusive content 🔥","status":"SENT","price":500,"createdAt":"2024-01-15T00:00:00.000Z","publishedAt":"2024-01-15T00:00:00.000Z","recipientCount":1250,"viewCount":890,"purchaseCount":156,"totalRevenue":78000},{"uuid":"e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9012","text":"Good morning! Hope you all have a great day ☀️","status":"SENT","price":null,"createdAt":"2024-01-14T00:00:00.000Z","publishedAt":"2024-01-14T00:00:00.000Z","recipientCount":1180,"viewCount":720,"purchaseCount":0,"totalRevenue":0}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/mass-messages/{messageUuid}":{"delete":{"summary":"Delete a mass message","description":"Delete/unsend a previously sent mass message.\n\nMass messages that were already purchased remain available to those recipients.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"deleteMassMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"}],"responses":{"204":{"description":"Mass message deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"patch":{"summary":"Update a scheduled mass message","description":"Update a scheduled mass message before it is sent.\n\nOnly scheduled mass messages can be updated.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"updateMassMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":5000},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"}},"price":{"type":"number","nullable":true,"minimum":300},"includedLists":{"type":"object","properties":{"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]}},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"excludedLists":{"type":"object","properties":{"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]}},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"scheduledAt":{"type":"string","format":"date-time","description":"Optional scheduled date/time in ISO 8601 format. Alias `scheduled_at` is also accepted."}}}}}},"responses":{"204":{"description":"Mass message updated successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/{userUuid}/messages/{messageUuid}":{"delete":{"summary":"Delete a message","description":"Delete/unsend a previously sent message from a chat conversation.\n\nOnly the sender can delete their own messages. Messages that have been purchased (paid content) cannot be deleted. Mass messages cannot be deleted via this endpoint.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"deleteMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"}],"responses":{"204":{"description":"Message deleted successfully"},"400":{"description":"Message cannot be deleted (e.g., purchased content)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/unread":{"get":{"summary":"Get unread chats, messages, and notifications count","description":"Returns the count of unread chats, total unread messages, and unread notifications by type for the authenticated user.\n\n<Info>Scope required: `read:chat`</Info>","operationId":"getUnreadChatsCount","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"Unread counts retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"unreadChatsCount":{"type":"number","description":"Number of conversations with unread messages"},"unreadMessagesCount":{"type":"number","description":"Total number of unread messages across all chats"},"unreadNotifications":{"type":"object","properties":{"newFollower":{"type":"number","description":"Number of unread new follower notifications"},"newPostComment":{"type":"number","description":"Number of unread post comment notifications"},"newPostLike":{"type":"number","description":"Number of unread post like notifications"},"newPurchase":{"type":"number","description":"Number of unread purchase notifications"},"newSubscriber":{"type":"number","description":"Number of unread new subscriber notifications"},"newTip":{"type":"number","description":"Number of unread tip notifications"},"newPromotion":{"type":"number","description":"Number of unread promotion notifications"}},"required":["newFollower","newPostComment","newPostLike","newPurchase","newSubscriber","newTip","newPromotion"],"description":"Counts of unread notifications by type"}},"required":["unreadChatsCount","unreadMessagesCount","unreadNotifications"]},"example":{"unreadChatsCount":5,"unreadMessagesCount":12,"unreadNotifications":{"newFollower":3,"newPostComment":2,"newPostLike":8,"newPurchase":1,"newSubscriber":4,"newTip":2,"newPromotion":0}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/statuses":{"post":{"summary":"Get online statuses for multiple users","description":"Returns the online status and last seen timestamp for multiple users in a single request.\n\nThis endpoint is optimized for batch lookups when you need to check the online status of multiple chat counterparts at once.\n\n<Info>Scope required: `read:chat`</Info>\n\n<Note>Maximum 100 user UUIDs per request. Users who have disabled online visibility will always appear as offline with no last seen timestamp.</Note>","operationId":"getBatchStatuses","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userUuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"Array of user UUIDs to check online status for (max 100)"}},"required":["userUuids"]}}}},"responses":{"200":{"description":"Online statuses retrieved successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","properties":{"isOnline":{"type":"boolean","description":"Whether the user is currently online"},"lastSeenAt":{"type":"string","nullable":true,"format":"date","description":"Last time the user was seen online (UTC)"}},"required":["isOnline","lastSeenAt"]},"description":"Map of user UUIDs to their online status"},"example":{"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8":{"isOnline":true,"lastSeenAt":"2024-01-15T00:00:00.000Z"},"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7":{"isOnline":false,"lastSeenAt":"2024-01-14T00:00:00.000Z"},"c3d4e5f6-7890-1234-5678-9abcdef01234":{"isOnline":false,"lastSeenAt":null}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/{userUuid}/media":{"get":{"summary":"Get media from a chat","description":"Returns a cursor-paginated list of media items shared between the authenticated user and the specified user. Media is extracted from chat messages and ordered by date (newest first).\n\n**Pagination Flow:**\n- First request: Omit the `cursor` parameter, returns first 20 media items (or specified limit)\n- Subsequent requests: Use the `nextCursor` from the previous response\n- End of results: `nextCursor` will be `null`\n\n```json\n{\n  \"data\": [...media items...],\n  \"nextCursor\": \"...\" // Pass this to the next request to get the following page\n}\n```\n\n<Info>Scope required: `read:chat`</Info>","operationId":"listMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"},{"schema":{"type":"string","description":"Cursor for fetching the next page of media"},"required":false,"description":"Cursor for fetching the next page of media","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["image","video","audio","document"],"description":"Filter by media type (image, video, audio, document)"},"required":false,"description":"Filter by media type (image, video, audio, document)","name":"mediaType","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20,"description":"Number of media items to return (1-50, default: 20)"},"required":false,"description":"Number of media items to return (1-50, default: 20)","name":"limit","in":"query"}],"responses":{"200":{"description":"Cursor-paginated list of media items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"messageUuid":{"type":"string","format":"uuid"},"mediaType":{"type":"string","enum":["image","video","audio","document","unknown"]},"created_at":{"type":"string","nullable":true,"format":"date"},"sentAt":{"type":"string","nullable":true,"format":"date"},"ownerUuid":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"variantType":{"type":"string","enum":["main","thumbnail","thumbnail_gallery","blurred"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["variantType","displayPosition","width","height","lengthMs"]}}},"required":["uuid","messageUuid","mediaType","created_at","sentAt","ownerUuid","name"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for fetching the next page, null if no more results"}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","messageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","mediaType":"image","created_at":"2024-01-15T00:00:00.000Z","sentAt":"2024-01-15T00:00:00.000Z","ownerUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","name":"Beach Sunset","variants":[{"variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg","width":1920,"height":1440,"lengthMs":null},{"variantType":"thumbnail_gallery","displayPosition":0,"url":"https://media.fanvue.com/gallery/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg","width":400,"height":300,"lengthMs":null}]},{"uuid":"b2c3d4e5-f6a7-8901-bcde-f12345678901","messageUuid":"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","mediaType":"video","created_at":"2024-01-14T00:00:00.000Z","sentAt":"2024-01-15T00:00:00.000Z","ownerUuid":"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","name":"Cooking Tutorial","variants":[{"variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/b2c3d4e5-f6a7-8901-bcde-f12345678901.mp4","width":1920,"height":1080,"lengthMs":45000},{"variantType":"thumbnail","displayPosition":0,"url":"https://media.fanvue.com/thumb/b2c3d4e5-f6a7-8901-bcde-f12345678901.jpg","width":1920,"height":1080,"lengthMs":null}]}],"nextCursor":"eyJzZW50QmVmb3JlIjoiMjAyNC0wMS0wOVQxMjowMDowMC4wMDBaIiwicmVjZWl2ZWRCZWZvcmUiOiIyMDI0LTAxLTA5VDExOjU4OjAwLjAwMFoifQ=="}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"No conversation found with the given user","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/{userUuid}/messages/{messageUuid}/media":{"get":{"summary":"Resolve media UUIDs for a chat message","description":"Resolves means: for each requested `mediaUuid`, lookup that media only within the specified `messageUuid`, then return its chat media payload (metadata + signed variant URLs) or a per-item error.\n\n<Info>Scope required: `read:chat`</Info>\n\n<Note>The `mediaUuids` query parameter is required and accepts up to 20 UUIDs.</Note>","operationId":"getMessageMediaByUuids","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of media UUIDs to resolve (required, max 20)"},"required":true,"description":"Comma-separated list of media UUIDs to resolve (required, max 20)","name":"mediaUuids","in":"query"},{"schema":{"type":"string","description":"Optional comma-separated list of variant types to include"},"required":false,"description":"Optional comma-separated list of variant types to include","name":"variants","in":"query"}],"responses":{"200":{"description":"Resolved media payload map","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"messageUuid":{"type":"string","format":"uuid"},"mediaType":{"type":"string","enum":["image","video","audio","document","unknown"]},"created_at":{"type":"string","nullable":true,"format":"date"},"sentAt":{"type":"string","nullable":true,"format":"date"},"ownerUuid":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"variantType":{"type":"string","enum":["main","thumbnail","thumbnail_gallery","blurred"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["variantType","displayPosition","width","height","lengthMs"]}}},"required":["uuid","messageUuid","mediaType","created_at","sentAt","ownerUuid","name"]},"description":"Map media UUID -> media payload (null when unavailable)"},"errors":{"type":"array","items":{"type":"object","properties":{"mediaUuid":{"type":"string","format":"uuid"},"code":{"type":"string","enum":["NOT_IN_MESSAGE","INTERNAL"]},"message":{"type":"string"}},"required":["mediaUuid","code","message"]}}},"required":["results","errors"]},"example":{"results":{"a1b2c3d4-e5f6-7890-abcd-ef1234567890":{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","messageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","mediaType":"image","created_at":"2024-01-15T00:00:00.000Z","sentAt":"2024-01-15T00:00:00.000Z","ownerUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","name":"Beach Sunset","variants":[{"variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg","width":1920,"height":1440,"lengthMs":null}]},"00000000-0000-0000-0000-000000000000":null},"errors":[{"mediaUuid":"00000000-0000-0000-0000-000000000000","code":"NOT_IN_MESSAGE","message":"Media UUID is not attached to this message"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Message not found or not accessible","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/lists/smart":{"get":{"summary":"Get smart lists","description":"Get all available smart lists with member counts.\n\nSmart lists are system-generated dynamic audience segments (not user-created lists). They are computed from relationship/subscription/payment state and update automatically.\n\nExamples include:\n- `subscribers`\n- `followers`\n- `auto_renewing`\n- `non_renewing`\n- `expired_subscribers`\n- `free_trial_subscribers`\n- `spent_more_than_50`\n\nFor `subscribers`, the count reflects current non-deleted subscription relationships that are contactable by the requesting creator.\n\n<Info>Scope required: `read:chat` `read:fan`</Info>","operationId":"getSmartLists","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"List of smart lists","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the smart list"},"uuid":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"],"description":"Smart list unique identifier"},"count":{"type":"number","description":"Number of members in this list"}},"required":["name","uuid","count"]}},"example":[{"name":"Subscribers","uuid":"subscribers","count":1250},{"name":"Auto-renewing","uuid":"auto_renewing","count":892},{"name":"Non-renewing","uuid":"non_renewing","count":358},{"name":"Followers","uuid":"followers","count":2156},{"name":"Free trial subscribers","uuid":"free_trial_subscribers","count":45},{"name":"Expired subscribers","uuid":"expired_subscribers","count":178},{"name":"Spent more than $50","uuid":"spent_more_than_50","count":423},{"name":"Muted","uuid":"muted","count":12}]}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/lists/smart/{uuid}":{"get":{"summary":"Get smart list members","description":"Get members of a specific smart list with pagination.\n\nSmart lists are system-generated dynamic audience segments (not user-created lists). The returned members are filtered by contactability and the selected smart list type.\n\n<Info>Scope required: `read:chat` `read:fan`</Info>","operationId":"getSmartListMembers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"],"description":"Smart list unique identifier"},"required":true,"description":"Smart list unique identifier","name":"uuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"Smart list members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"User UUID"},"displayName":{"type":"string","description":"User's display name"},"handle":{"type":"string","description":"User's handle"},"isCreator":{"type":"boolean","description":"Whether user is a creator"}},"required":["uuid","displayName","handle","isCreator"]},"description":"Members of the smart list"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"550e8400-e29b-41d4-a716-446655440000","displayName":"Sarah Johnson","handle":"sarah_j","isCreator":false},{"uuid":"550e8400-e29b-41d4-a716-446655440001","displayName":"Mike Chen","handle":"mike_creates","isCreator":true},{"uuid":"550e8400-e29b-41d4-a716-446655440002","displayName":"Alex Rivera","handle":"alexr","isCreator":false}],"pagination":{"page":1,"size":20,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/lists/custom":{"get":{"summary":"Get custom lists","description":"Get user's custom lists with member counts. Supports pagination and optional name search.\n\n<Info>Scope required: `read:chat` `read:fan`</Info>","operationId":"getCustomLists","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","description":"Search term to filter lists by name"},"required":false,"description":"Search term to filter lists by name","name":"search","in":"query"}],"responses":{"200":{"description":"List of custom lists","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Custom list UUID"},"name":{"type":"string","description":"Custom list name"},"membersCount":{"type":"number","description":"Number of members in this list"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the list was created"}},"required":["uuid","name","membersCount","createdAt"]},"description":"Array of custom lists"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"123e4567-e89b-12d3-a456-426614174000","name":"VIP Subscribers","membersCount":47,"createdAt":"2024-01-15T10:30:00Z"},{"uuid":"123e4567-e89b-12d3-a456-426614174001","name":"New Followers","membersCount":128,"createdAt":"2024-02-20T09:15:00Z"},{"uuid":"123e4567-e89b-12d3-a456-426614174002","name":"Content Collaborators","membersCount":23,"createdAt":"2024-01-08T11:20:00Z"}],"pagination":{"page":1,"size":20,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"post":{"summary":"Create a custom list","description":"Create a new custom list for organizing contacts.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"createCustomList","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name of the custom list"}},"required":["name"]}}}},"responses":{"201":{"description":"Custom list created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID of the created list"},"name":{"type":"string","description":"Name of the created list"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the list was created"}},"required":["uuid","name","createdAt"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174003","name":"Top Supporters","createdAt":"2024-03-15T14:30:00Z"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"409":{"description":"A list with this name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/lists/custom/{uuid}":{"get":{"summary":"Get custom list members","description":"Get members of a specific custom list with pagination.\n\n<Info>Scope required: `read:chat` `read:fan`</Info>","operationId":"getCustomListMembers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"Custom list members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"User UUID"},"displayName":{"type":"string","description":"User's display name"},"handle":{"type":"string","description":"User's handle"},"isCreator":{"type":"boolean","description":"Whether user is a creator"}},"required":["uuid","displayName","handle","isCreator"]},"description":"Members of the custom list"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","displayName":"Emma Thompson","handle":"emma_art","isCreator":true},{"uuid":"6ba7b811-9dad-11d1-80b4-00c04fd430c8","displayName":"Jake Martinez","handle":"jakethefan","isCreator":false},{"uuid":"6ba7b812-9dad-11d1-80b4-00c04fd430c8","displayName":"Sophie Williams","handle":"sophie_w","isCreator":true},{"uuid":"6ba7b813-9dad-11d1-80b4-00c04fd430c8","displayName":"David Kim","handle":"davidk_collector","isCreator":false}],"pagination":{"page":1,"size":20,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Custom list not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"patch":{"summary":"Rename a custom list","description":"Update the name of an existing custom list.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"updateCustomList","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"New name for the custom list"}},"required":["name"]}}}},"responses":{"204":{"description":"Custom list updated successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Custom list not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"A list with this name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"delete":{"summary":"Delete a custom list","description":"Delete a custom list. All members will be removed from the list.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"deleteCustomList","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"}],"responses":{"204":{"description":"Custom list deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Custom list not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/lists/custom/{uuid}/members":{"post":{"summary":"Add members to a custom list","description":"Add one or more users to a custom list. Existing members will be skipped.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"addMembersToCustomList","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userUuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"UUIDs of users to add to the list (max 100)"}},"required":["userUuids"]}}}},"responses":{"201":{"description":"Members added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"number","description":"Number of members added to the list"},"skipped":{"type":"number","description":"Number of members skipped (already in list)"}},"required":["added","skipped"]},"example":{"added":5,"skipped":0}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Custom list not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/lists/custom/{uuid}/members/{userUuid}":{"delete":{"summary":"Remove a member from a custom list","description":"Remove a user from a custom list.\n\n<Info>Scope required: `write:chat`</Info>","operationId":"removeMemberFromCustomList","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"User UUID to remove from the list"},"required":true,"description":"User UUID to remove from the list","name":"userUuid","in":"path"}],"responses":{"204":{"description":"Member removed successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Custom list or member not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/templates":{"get":{"summary":"Get list of template messages","description":"Returns a paginated list of template messages. Optionally filter by folder name using case-insensitive partial matching.\n\n<Info>Scope required: `read:chat`</Info>","operationId":"listTemplateMessages","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","description":"Filter by folder name (case-insensitive partial match)"},"required":false,"description":"Filter by folder name (case-insensitive partial match)","name":"folderName","in":"query"}],"responses":{"200":{"description":"List of template messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Template message UUID"},"text":{"type":"string","nullable":true,"description":"Message text content"},"price":{"type":"number","nullable":true,"description":"Message price in cents (null for free messages)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the message"},"folderName":{"type":"string","nullable":true,"description":"Name of the folder containing this template"}},"required":["uuid","text","price","mediaUuids","folderName"]},"description":"Array of template messages"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"123e4567-e89b-12d3-a456-426614174000","text":"Hey! Thanks for subscribing! Check out my latest exclusive content 🔥","price":999,"folderName":"Welcome Messages","mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"]},{"uuid":"123e4567-e89b-12d3-a456-426614174001","text":"Happy Friday! Here's something special just for you 💝","price":null,"folderName":"Promotions","mediaUuids":[]},{"uuid":"123e4567-e89b-12d3-a456-426614174002","text":"Check out this exclusive content! Limited time offer 🎁","price":1499,"folderName":"Promotions","mediaUuids":["8d9e6679-7425-40de-944b-e07fc1f90ae8","9e9e6679-7425-40de-944b-e07fc1f90ae9"]}],"pagination":{"page":1,"size":20,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/chats/templates/{templateUuid}":{"get":{"summary":"Get a single template message","description":"Returns a specific template message by UUID.\n\n<Info>Scope required: `read:chat`</Info>","operationId":"getTemplateMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Template message UUID"},"required":true,"description":"Template message UUID","name":"templateUuid","in":"path"}],"responses":{"200":{"description":"Template message details","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Template message UUID"},"text":{"type":"string","nullable":true,"description":"Message text content"},"price":{"type":"number","nullable":true,"description":"Message price in cents (null for free messages)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the message"},"folderName":{"type":"string","nullable":true,"description":"Name of the folder containing this template"}},"required":["uuid","text","price","mediaUuids","folderName"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","text":"Hey! Thanks for subscribing! Check out my latest exclusive content 🔥","price":999,"folderName":"Welcome Messages","mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Template message not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators":{"get":{"summary":"Get agency creators","description":"Returns a paginated list of creators associated with the authenticated agency user's organization.\n\n    <Info>Scope required: `read:creator`</Info>","operationId":"listCreators","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of creators","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"},"role":{"type":"string"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"description":"Array of creators"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"},{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/followers":{"get":{"summary":"Get creator followers","description":"Returns a paginated list of users who follow the specified creator.\n\n    <Info>Scopes required: `read:creator`, `read:fan`</Info>","operationId":"listCreatorFollowers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of creator followers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"description":"Array of followers"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","handle":"alex-fan","nickname":"AlexF","displayName":"Alex Fan","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"},{"uuid":"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","handle":"jordan-cool","nickname":null,"displayName":"Jordan Cool","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"}],"pagination":{"page":1,"size":2,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/subscribers":{"get":{"summary":"Get creator subscribers","description":"Returns a paginated list of users subscribed to the specified creator.\n\n    <Info>Scopes required: `read:creator`, `read:fan`</Info>","operationId":"listCreatorSubscribers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of creator subscribers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"description":"Array of subscribers"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","handle":"alex-fan","nickname":"AlexF","displayName":"Alex Fan","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"},{"uuid":"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","handle":"jordan-cool","nickname":null,"displayName":"Jordan Cool","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats":{"get":{"summary":"Get chats of a creator","description":"Returns a paginated list of chats for the specified creator.\n\n    <Info>Scopes required: `read:creator`, `read:chat`</Info>","operationId":"listCreatorChats","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of creator chats","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":"string","nullable":true,"format":"date"},"lastMessageAt":{"type":"string","nullable":true,"format":"date","description":"Date of the last message in this chat"},"isRead":{"type":"boolean","description":"Whether the chat is marked as read (true) or unread (false)"},"isMuted":{"type":"boolean"},"unreadMessagesCount":{"type":"number"},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"lastMessage":{"type":"object","nullable":true,"properties":{"text":{"type":"string","nullable":true},"type":{"type":"string","enum":["AUTOMATED_CANCELED","AUTOMATED_NEW_FOLLOWER","AUTOMATED_NEW_PURCHASE","AUTOMATED_NEW_SUBSCRIBER","AUTOMATED_RE_SUBSCRIBED","AUTOMATED_RENEWED","AUTOMATED_CHAT_MESSAGE_REPLY","AUTOMATED_FIRST_MESSAGE_REPLY","CHAT_TEXT_GENERATION","CHAT_TEXT_REPLY","CHAT_TEXT_REWRITE","SINGLE_RECIPIENT","TIP","VOICE_CALL","BROADCAST","GHOST_PROMOTION"]},"uuid":{"type":"string"},"sentAt":{"type":"string","nullable":true,"format":"date"},"hasMedia":{"type":"boolean","nullable":true},"mediaType":{"type":"string","nullable":true,"enum":["image","video","audio","document"]},"senderUuid":{"type":"string","format":"uuid"},"sentByUserId":{"type":"string","nullable":true,"format":"uuid","description":"UUID of the team member who sent the message on behalf of the creator, or null if sent directly by the creator"}},"required":["text","type","uuid","sentAt","hasMedia","mediaType","senderUuid","sentByUserId"]}},"required":["createdAt","lastMessageAt","isRead","isMuted","unreadMessagesCount","user","lastMessage"]},"description":"Array of chats"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"createdAt":"2024-01-15T00:00:00.000Z","lastMessageAt":"2024-01-15T00:00:00.000Z","isRead":false,"isMuted":false,"unreadMessagesCount":3,"user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"lastMessage":{"uuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","text":"Hey there! How are you doing?","type":"SINGLE_RECIPIENT","sentAt":"2024-01-15T00:00:00.000Z","hasMedia":true,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","sentByUserId":null}},{"createdAt":"2024-01-14T00:00:00.000Z","lastMessageAt":null,"isRead":true,"isMuted":true,"unreadMessagesCount":0,"user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"lastMessage":null},{"createdAt":"2024-01-15T00:00:00.000Z","lastMessageAt":"2024-01-15T00:00:00.000Z","isRead":true,"isMuted":false,"unreadMessagesCount":0,"user":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","handle":"johnny-doey","nickname":"JohnnyD","displayName":"Johnny Doey","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"lastMessage":{"uuid":"c3d4e5f6-7890-1234-5678-9abcdef01234","text":"Check out my new post!","type":"BROADCAST","sentAt":"2024-01-15T00:00:00.000Z","hasMedia":true,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","sentByUserId":null}}],"pagination":{"page":1,"size":2,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"post":{"summary":"Create new chat as creator","description":"Create a new chat conversation as a creator.\n\n    <Info>Scopes required: `write:chat`, `read:creator`</Info>","operationId":"createCreatorChat","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid"}},"required":["userUuid"]}}}},"responses":{"201":{"description":"Chat created","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Chat created successfully"}}}},"400":{"description":"Bad Request - API version not supported OR user contactability validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ContactabilityError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/{userUuid}/message":{"post":{"summary":"Send a message as creator","description":"Send a message as a creator in an existing chat conversation. The message can include text, media attachments, and optional pricing for pay-to-view content.\n\n    <Info>Scopes required: `write:chat`, `read:creator`</Info>","operationId":"sendCreatorMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","nullable":true,"minLength":1,"maxLength":5000},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"}},"price":{"type":"number","nullable":true,"minimum":300},"templateUuid":{"type":"string","nullable":true,"format":"uuid"}}}}}},"responses":{"201":{"description":"Message sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"messageUuid":{"type":"string","format":"uuid"}},"required":["messageUuid"]},"example":{"messageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"}}}},"400":{"description":"Bad Request - API version not supported OR user contactability validation failed OR message validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ContactabilityError"},{"$ref":"#/components/schemas/MessageValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/mass-messages":{"post":{"summary":"Send a mass message as creator","description":"Send a message to multiple users based on selected lists as a creator.  \nIf `scheduledAt` (or alias `scheduled_at`) is provided, the message is queued for scheduled delivery instead of being sent immediately.\n\n    <Info>Scopes required: `write:chat`, `read:creator`, `read:fan`</Info>","operationId":"sendCreatorMassMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":5000},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"}},"price":{"type":"number","nullable":true,"minimum":300},"includedLists":{"type":"object","properties":{"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]}},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"excludedLists":{"type":"object","properties":{"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]}},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"scheduledAt":{"type":"string","format":"date-time","description":"Optional scheduled date/time in ISO 8601 format. Alias `scheduled_at` is also accepted."}},"required":["includedLists"]}}}},"responses":{"201":{"description":"Mass message sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"recipientCount":{"type":"number"},"createdAt":{"type":"string","nullable":true,"format":"date"}},"required":["id","recipientCount","createdAt"]},"example":{"id":"f1e2d3c4-b5a6-9788-c0d1-e2f3g4h5i6j7","recipientCount":1250,"createdAt":"2024-01-15T00:00:00.000Z"}}}},"400":{"description":"Bad Request - API version not supported OR user contactability validation failed OR message validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ContactabilityError"},{"$ref":"#/components/schemas/MessageValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"get":{"summary":"List mass messages for a creator","description":"Returns a paginated list of mass (broadcast) messages sent by the specified creator, including delivery and engagement statistics.\n\nEach item includes recipient count, view count, purchase count, and total revenue generated.\n\nUse the `includeDeleted` query parameter to also retrieve deleted (unsent) mass messages. Deleted messages will have a status of `UNSENT`.\n\n<Info>Scopes required: `read:creator`, `read:chat`</Info>","operationId":"listCreatorMassMessages","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Whether to include deleted (unsent) mass messages in the results. Defaults to false."},"required":false,"description":"Whether to include deleted (unsent) mass messages in the results. Defaults to false.","name":"includeDeleted","in":"query"}],"responses":{"200":{"description":"List of mass messages with statistics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"text":{"type":"string","nullable":true},"status":{"type":"string","enum":["SENT","UNSENT","SENDING","FAILED","MODERATED","SCHEDULED"],"description":"Current status of the mass message"},"price":{"type":"number","nullable":true,"description":"Price in cents for pay-to-view content, or null if free"},"createdAt":{"type":"string","nullable":true,"format":"date"},"publishedAt":{"type":"string","nullable":true,"format":"date","description":"When the message was published/sent"},"recipientCount":{"type":"number","description":"Number of recipients the message was sent to"},"viewCount":{"type":"number","description":"Number of recipients who have viewed the message"},"purchaseCount":{"type":"number","description":"Number of recipients who purchased the pay-to-view content"},"totalRevenue":{"type":"number","description":"Total revenue generated from purchases of this message (in cents)"}},"required":["uuid","text","status","price","createdAt","publishedAt","recipientCount","viewCount","purchaseCount","totalRevenue"]},"description":"Array of mass messages with delivery and engagement statistics"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90","text":"Hey everyone! Check out my new exclusive content 🔥","status":"SENT","price":500,"createdAt":"2024-01-15T00:00:00.000Z","publishedAt":"2024-01-15T00:00:00.000Z","recipientCount":1250,"viewCount":890,"purchaseCount":156,"totalRevenue":78000},{"uuid":"e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9012","text":"Good morning! Hope you all have a great day ☀️","status":"SENT","price":null,"createdAt":"2024-01-14T00:00:00.000Z","publishedAt":"2024-01-14T00:00:00.000Z","recipientCount":1180,"viewCount":720,"purchaseCount":0,"totalRevenue":0}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/mass-messages/{messageUuid}":{"delete":{"summary":"Delete a creator mass message","description":"Delete/unsend a previously sent mass message for the specified creator.\n\nMass messages that were already purchased remain available to those recipients.\n\n<Info>Scopes required: `write:chat`, `read:creator`</Info>","operationId":"deleteCreatorMassMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"}],"responses":{"204":{"description":"Mass message deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"patch":{"summary":"Update a creator scheduled mass message","description":"Update a scheduled mass message for the specified creator before it is sent.\n\nOnly scheduled mass messages can be updated.\n\n<Info>Scopes required: `write:chat`, `read:creator`</Info>","operationId":"updateCreatorMassMessage","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":5000},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"}},"price":{"type":"number","nullable":true,"minimum":300},"includedLists":{"type":"object","properties":{"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]}},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"excludedLists":{"type":"object","properties":{"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"]}},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"scheduledAt":{"type":"string","format":"date-time","description":"Optional scheduled date/time in ISO 8601 format. Alias `scheduled_at` is also accepted."}}}}}},"responses":{"204":{"description":"Mass message updated successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/{userUuid}/messages":{"get":{"summary":"Get messages between a creator and a user","description":"Returns a paginated list of text messages between the specified creator and user. Messages are ordered by creation date (newest first).\n\n    <Info>Scopes required: `read:creator`, `read:chat`</Info>","operationId":"listCreatorMessages","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to mark the chat as read after retrieving messages"},"required":false,"description":"Whether to mark the chat as read after retrieving messages","name":"markAsRead","in":"query"}],"responses":{"200":{"description":"List of messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"text":{"type":"string","nullable":true},"sentAt":{"type":"string","nullable":true,"format":"date"},"sender":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"}},"required":["uuid","handle"]},"recipient":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"}}},"hasMedia":{"type":"boolean","nullable":true},"mediaType":{"type":"string","nullable":true,"enum":["image","video","audio","document"]},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ordered list of media UUIDs attached to this message (display order)"},"type":{"type":"string","enum":["AUTOMATED_CANCELED","AUTOMATED_NEW_FOLLOWER","AUTOMATED_NEW_PURCHASE","AUTOMATED_NEW_SUBSCRIBER","AUTOMATED_RE_SUBSCRIBED","AUTOMATED_RENEWED","AUTOMATED_CHAT_MESSAGE_REPLY","AUTOMATED_FIRST_MESSAGE_REPLY","CHAT_TEXT_GENERATION","CHAT_TEXT_REPLY","CHAT_TEXT_REWRITE","SINGLE_RECIPIENT","TIP","VOICE_CALL"]},"pricing":{"type":"object","nullable":true,"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Pricing information for pay-to-view messages"},"purchasedAt":{"type":"string","nullable":true,"format":"date","description":"Timestamp when this message was purchased, or null if not purchased"},"sentByUserId":{"type":"string","nullable":true,"format":"uuid","description":"UUID of the team member who sent the message on behalf of the creator, or null if sent directly by the creator"},"isRead":{"type":"boolean","description":"Whether the message has been read by the recipient"}},"required":["uuid","text","sentAt","sender","recipient","hasMedia","mediaType","mediaUuids","type","pricing","purchasedAt","sentByUserId","isRead"]},"description":"Array of messages in the conversation"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","text":"Hey there! How are you doing?","sentAt":"2024-01-15T00:00:00.000Z","sender":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"recipient":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","handle":"johnny-doey","nickname":"JohnnyD","displayName":"Johnny Doey","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"type":"SINGLE_RECIPIENT","hasMedia":false,"mediaType":null,"mediaUuids":[],"pricing":null,"purchasedAt":null,"sentByUserId":null},{"uuid":"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","text":"I'm doing great! Thanks for asking.","sentAt":"2024-01-15T00:00:00.000Z","sender":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","handle":"johnny-doey","nickname":"JohnnyD","displayName":"Johnny Doey","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"recipient":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"type":"SINGLE_RECIPIENT","hasMedia":true,"mediaType":"image","mediaUuids":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"pricing":{"USD":{"price":500}},"purchasedAt":"2024-01-15T00:00:00.000Z","sentByUserId":null}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"No conversation found with the given user","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/{userUuid}":{"patch":{"summary":"Update a creator's chat with a user","description":"Update properties of a chat conversation between the specified creator and user (e.g. mark as read, mute, nickname). Used by agency mirror clients to mark conversations as read on behalf of the creator.\n\n    <Info>Scopes required: `write:chat`, `read:creator`</Info>","operationId":"updateCreatorChat","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isRead":{"type":"boolean","description":"Whether the chat should be marked as read (true) or unread (false)"},"isMuted":{"type":"boolean","description":"Whether the chat should be muted (true) or unmuted (false)"},"nickname":{"type":"string","maxLength":30,"description":"Custom nickname for the chat counterpart (max 30 characters)"}}}}}},"responses":{"204":{"description":"Chat updated successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"No conversation found with the given user","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/{userUuid}/media":{"get":{"summary":"Get media from a creator's chat","description":"Returns a cursor-paginated list of media items shared between the specified creator and user. Media is extracted from chat messages and ordered by date (newest first).\n\n**Pagination Flow:**\n- First request: Omit the `cursor` parameter, returns first 20 media items (or specified limit)\n- Subsequent requests: Use the `nextCursor` from the previous response\n- End of results: `nextCursor` will be `null`\n\n```json\n{\n  \"data\": [...media items...],\n  \"nextCursor\": \"...\" // Pass this to the next request to get the following page\n}\n```\n\n<Info>Scopes required: `read:creator`, `read:chat`</Info>","operationId":"listCreatorChatMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"},{"schema":{"type":"string","description":"Cursor for fetching the next page of media"},"required":false,"description":"Cursor for fetching the next page of media","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["image","video","audio","document"],"description":"Filter by media type (image, video, audio, document)"},"required":false,"description":"Filter by media type (image, video, audio, document)","name":"mediaType","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20,"description":"Number of media items to return (1-50, default: 20)"},"required":false,"description":"Number of media items to return (1-50, default: 20)","name":"limit","in":"query"}],"responses":{"200":{"description":"Cursor-paginated list of media items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"messageUuid":{"type":"string","format":"uuid"},"mediaType":{"type":"string","enum":["image","video","audio","document","unknown"]},"created_at":{"type":"string","nullable":true,"format":"date"},"sentAt":{"type":"string","nullable":true,"format":"date"},"ownerUuid":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"variantType":{"type":"string","enum":["main","thumbnail","thumbnail_gallery","blurred"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["variantType","displayPosition","width","height","lengthMs"]}}},"required":["uuid","messageUuid","mediaType","created_at","sentAt","ownerUuid","name"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for fetching the next page, null if no more results"}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","messageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","mediaType":"image","created_at":"2024-01-15T00:00:00.000Z","sentAt":"2024-01-15T00:00:00.000Z","ownerUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","name":"Beach Sunset","variants":[{"variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg","width":1920,"height":1440,"lengthMs":null},{"variantType":"thumbnail_gallery","displayPosition":0,"url":"https://media.fanvue.com/gallery/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg","width":400,"height":300,"lengthMs":null}]},{"uuid":"b2c3d4e5-f6a7-8901-bcde-f12345678901","messageUuid":"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","mediaType":"video","created_at":"2024-01-14T00:00:00.000Z","sentAt":"2024-01-15T00:00:00.000Z","ownerUuid":"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","name":"Cooking Tutorial","variants":[{"variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/b2c3d4e5-f6a7-8901-bcde-f12345678901.mp4","width":1920,"height":1080,"lengthMs":45000},{"variantType":"thumbnail","displayPosition":0,"url":"https://media.fanvue.com/thumb/b2c3d4e5-f6a7-8901-bcde-f12345678901.jpg","width":1920,"height":1080,"lengthMs":null}]}],"nextCursor":"eyJzZW50QmVmb3JlIjoiMjAyNC0wMS0wOVQxMjowMDowMC4wMDBaIiwicmVjZWl2ZWRCZWZvcmUiOiIyMDI0LTAxLTA5VDExOjU4OjAwLjAwMFoifQ=="}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"No conversation found with the given user","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/{userUuid}/messages/{messageUuid}/media":{"get":{"summary":"Resolve media UUIDs for a creator chat message","description":"Resolves means: for each requested `mediaUuid`, lookup that media only within the specified `messageUuid` in this creator conversation, then return its chat media payload (metadata + signed variant URLs) or a per-item error.\n\n<Info>Scopes required: `read:creator`, `read:chat`</Info>\n\n<Note>The `mediaUuids` query parameter is required and accepts up to 20 UUIDs.</Note>","operationId":"getCreatorMessageMediaByUuids","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of media UUIDs to resolve (required, max 20)"},"required":true,"description":"Comma-separated list of media UUIDs to resolve (required, max 20)","name":"mediaUuids","in":"query"},{"schema":{"type":"string","description":"Optional comma-separated list of variant types to include"},"required":false,"description":"Optional comma-separated list of variant types to include","name":"variants","in":"query"}],"responses":{"200":{"description":"Resolved media payload map","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"messageUuid":{"type":"string","format":"uuid"},"mediaType":{"type":"string","enum":["image","video","audio","document","unknown"]},"created_at":{"type":"string","nullable":true,"format":"date"},"sentAt":{"type":"string","nullable":true,"format":"date"},"ownerUuid":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"variantType":{"type":"string","enum":["main","thumbnail","thumbnail_gallery","blurred"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["variantType","displayPosition","width","height","lengthMs"]}}},"required":["uuid","messageUuid","mediaType","created_at","sentAt","ownerUuid","name"]},"description":"Map media UUID -> media payload (null when unavailable)"},"errors":{"type":"array","items":{"type":"object","properties":{"mediaUuid":{"type":"string","format":"uuid"},"code":{"type":"string","enum":["NOT_IN_MESSAGE","INTERNAL"]},"message":{"type":"string"}},"required":["mediaUuid","code","message"]}}},"required":["results","errors"]},"example":{"results":{"a1b2c3d4-e5f6-7890-abcd-ef1234567890":{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","messageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6","mediaType":"image","created_at":"2024-01-15T00:00:00.000Z","sentAt":"2024-01-15T00:00:00.000Z","ownerUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","name":"Beach Sunset","variants":[{"variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg","width":1920,"height":1440,"lengthMs":null}]},"00000000-0000-0000-0000-000000000000":null},"errors":[{"mediaUuid":"00000000-0000-0000-0000-000000000000","code":"NOT_IN_MESSAGE","message":"Media UUID is not attached to this message"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Message not found or not accessible","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/media":{"get":{"summary":"Get creator's media list","description":"Returns a paginated list of media items for the specified creator.\n\n    For media with status other than FINALISED, only uuid and status are returned.\n    For FINALISED media, all details including variants are included.\n\n    <Info>Scopes required: `read:creator`, `read:media`</Info>","operationId":"getCreatorMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","enum":["image","video","audio","document"]},"required":false,"name":"mediaType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"folderName","in":"query"},{"schema":{"type":"string","enum":["subscribers","followers","ppv","mass_messages"]},"required":false,"name":"usage","in":"query"},{"schema":{"type":"string","format":"uuid","description":"UUID of the user to check media purchases against. When provided, each media item will include a purchasedByFan boolean indicating if that user has purchased it."},"required":false,"description":"UUID of the user to check media purchases against. When provided, each media item will include a purchasedByFan boolean indicating if that user has purchased it.","name":"purchasedBy","in":"query"},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MediaStatus"},"description":"Comma-separated list of media status values"},"required":false,"name":"status","in":"query","style":"form","explode":false},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MediaVariantType"},"description":"Comma-separated list of media variant types"},"required":false,"name":"variants","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"List of creator media","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]}},"required":["uuid","status"]},{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]},"createdAt":{"type":"string","nullable":true,"format":"date"},"url":{"type":"string"},"caption":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":"number","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"variantType":{"type":"string","enum":["blurred","main","thumbnail","thumbnail_gallery"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"}},"required":["uuid","status","createdAt","caption","description","name","mediaType","recommendedPrice"]}]},"description":"Array of media items"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","status":"ready","createdAt":"2024-01-15T00:00:00.000Z","caption":"Check out my latest video!","description":"Behind the scenes of my photoshoot","name":"photoshoot-video.mp4","mediaType":"video","recommendedPrice":500,"variants":[{"uuid":"e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b","variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.mp4","width":1920,"height":1080,"lengthMs":45000},{"uuid":"f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c","variantType":"thumbnail","displayPosition":1,"url":"https://media.fanvue.com/thumb/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":320,"height":180,"lengthMs":null},{"uuid":"a7b8c9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d","variantType":"blurred","displayPosition":2,"url":"https://media.fanvue.com/blur/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.mp4","width":1920,"height":1080,"lengthMs":45000}]},{"uuid":"b8c9d0e1-2f3a-4b5c-6d7e-8f9a0b1c2d3e","status":"processing"}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/media/{uuid}":{"get":{"summary":"Get creator's media by UUID","description":"Returns a specific media item by its UUID for the specified creator.\n\n    For media with status other than FINALISED, only uuid and status are returned.\n    For FINALISED media, all details including variants are included.\n\n    <Warning>Media URLs are only available through variants.\n    Specify the `variants` query parameter (e.g., `?variants=main,thumbnail,blurred`)\n    to include them in the response. Without this parameter, the `variants` field\n    will be an empty array and no media URLs will be returned.</Warning>\n\n    <Info>Scopes required: `read:creator`, `read:media`</Info>","operationId":"getCreatorMediaByUuid","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the user to check media purchase against. When provided, the media item will include a purchasedByFan boolean indicating if that user has purchased it."},"required":false,"description":"UUID of the user to check media purchase against. When provided, the media item will include a purchasedByFan boolean indicating if that user has purchased it.","name":"purchasedBy","in":"query"},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MediaVariantType"},"description":"Comma-separated list of media variant types"},"required":false,"name":"variants","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"Media item","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]}},"required":["uuid","status"]},{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]},"createdAt":{"type":"string","nullable":true,"format":"date"},"url":{"type":"string"},"caption":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":"number","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"variantType":{"type":"string","enum":["blurred","main","thumbnail","thumbnail_gallery"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"}},"required":["uuid","status","createdAt","caption","description","name","mediaType","recommendedPrice"]}]},"example":{"uuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","status":"ready","createdAt":"2024-01-15T00:00:00.000Z","caption":"Sunset at the beach","description":null,"name":"beach-sunset.jpg","mediaType":"image","recommendedPrice":null,"variants":[{"uuid":"c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f","variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":3840,"height":2160,"lengthMs":null},{"uuid":"d0e1f2a3-4b5c-6d7e-8f9a-0b1c2d3e4f5a","variantType":"thumbnail","displayPosition":1,"url":"https://media.fanvue.com/thumb/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":320,"height":180,"lengthMs":null},{"uuid":"e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b","variantType":"thumbnail_gallery","displayPosition":2,"url":"https://media.fanvue.com/gallery/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":400,"height":300,"lengthMs":null},{"uuid":"f2a3b4c5-6d7e-8f9a-0b1c-2d3e4f5a6b7c","variantType":"blurred","displayPosition":3,"url":"https://media.fanvue.com/blur/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":3840,"height":2160,"lengthMs":null}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/insights/earnings":{"get":{"summary":"Get earnings data for a creator","description":"Returns cursor-paginated invoice data for the specified creator over a specified time period. Each transaction includes information about the fan who made the payment.\n\n<Info>Scopes required: `read:creator`, `read:insights`</Info>","operationId":"getCreatorEarnings","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z)."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EarningSource"},"description":"Comma-separated list of earning sources"},"required":false,"description":"Comma-separated list of earning sources. Default: all","name":"source","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Cursor for pagination - If given, pass `nextCursor` to get the next page."},"required":false,"description":"Cursor for pagination - If given, pass `nextCursor` to get the next page.","name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20,"description":"Number of items to return per page (1-50, default: 20)"},"required":false,"description":"Number of items to return per page (1-50, default: 20)","name":"size","in":"query"}],"responses":{"200":{"description":"Creator earnings data with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Payment date as UTC ISO 8601 datetime string"},"gross":{"type":"number","description":"Amount the fan paid, converted to USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"},"currency":{"type":"string","nullable":true,"description":"Informational only — the local currency the fan originally paid in (e.g. 'BRL'). The gross and net amounts are already converted to USD cents regardless of this value."},"source":{"$ref":"#/components/schemas/EarningSource"},"transactionOrderId":{"type":"string","description":"Transaction order ID"},"transactionOrderStatus":{"type":"string","enum":["availableForPayout","pendingBalance"],"description":"Transaction order status"},"messageUuid":{"type":"string","format":"uuid","description":"Message UUID when source is message (e.g. paid chat or broadcast message)"},"postUuid":{"type":"string","format":"uuid","description":"Post UUID when source is post"},"user":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"}},"required":["uuid","handle","displayName","nickname","isTopSpender"],"description":"Fan's user information (null for transactions without a fan like referrals, affiliates)"}},"required":["date","gross","net","currency","source","transactionOrderId","transactionOrderStatus","user"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page, null if no more data"}},"required":["data","nextCursor"]},"example":{"data":[{"date":"2024-01-15T00:00:00.000Z","gross":5000,"net":4250,"currency":"USD","source":"subscription","transactionOrderId":"FV-ORDER-123","transactionOrderStatus":"availableForPayout","user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}},{"date":"2024-01-14T00:00:00.000Z","gross":2500,"net":2125,"currency":"USD","source":"tip","transactionOrderId":"FV-ORDER-124","transactionOrderStatus":"pendingBalance","user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}}],"nextCursor":"eyJkYXRlIjoiMjAyNC0wMS0xNVQwMDowMDowMC4wMDBaIn0"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination) OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/insights/earnings/summary":{"get":{"summary":"Get aggregated earnings summary for a creator","description":"Returns pre-aggregated earnings metrics for the specified creator, including all-time totals, month-over-month comparisons, source/type breakdowns, chart series, and averages.\n\n<Info>Scopes required: `read:creator`, `read:insights`</Info>","operationId":"getCreatorEarningsSummary","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z)."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.","name":"endDate","in":"query"},{"schema":{"type":"string","enum":["day","week"],"default":"day","description":"Aggregation granularity for the over-time chart"},"required":false,"description":"Aggregation granularity for the over-time chart","name":"granularity","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA timezone used for period grouping and month boundaries (e.g., Europe/London, America/New_York)"},"required":false,"description":"IANA timezone used for period grouping and month boundaries (e.g., Europe/London, America/New_York)","name":"timezone","in":"query"}],"responses":{"200":{"description":"Creator aggregated earnings summary","content":{"application/json":{"schema":{"type":"object","properties":{"totals":{"type":"object","properties":{"allTime":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"thisMonth":{"type":"object","properties":{"gross":{"type":"number"},"net":{"type":"number"},"previousMonthGross":{"type":"number"},"previousMonthNet":{"type":"number"},"grossChangePercentage":{"type":"number","nullable":true},"netChangePercentage":{"type":"number","nullable":true}},"required":["gross","net","previousMonthGross","previousMonthNet","grossChangePercentage","netChangePercentage"]}},"required":["allTime","thisMonth"]},"breakdownBySource":{"type":"object","properties":{"subs":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"messages":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"posts":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"tips":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"referrals":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"renewals":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"other":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]}},"required":["subs","messages","posts","tips","referrals","renewals","other"]},"earningsByType":{"type":"object","properties":{"renewals":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"messages":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"tips":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"subs":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]}},"required":["renewals","messages","tips","subs"]},"overTime":{"type":"array","items":{"type":"object","properties":{"periodStart":{"type":"string","format":"date-time","description":"Start of the aggregation bucket in ISO 8601 with timezone offset"},"gross":{"type":"number","description":"Amount fans paid in this bucket, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees in this bucket, in USD cents"}},"required":["periodStart","gross","net"]}},"averageByDayOfWeek":{"type":"object","properties":{"1":{"type":"number"},"2":{"type":"number"},"3":{"type":"number"},"4":{"type":"number"},"5":{"type":"number"},"6":{"type":"number"},"7":{"type":"number"}},"required":["1","2","3","4","5","6","7"],"description":"Average gross earnings by ISO day-of-week (1=Monday, 7=Sunday)"},"averageByHourOfDay":{"type":"object","additionalProperties":{"type":"number"},"description":"Average gross earnings by hour-of-day in the selected timezone (0-23)"},"period":{"type":"object","properties":{"startDate":{"type":"string","nullable":true},"endDate":{"type":"string","nullable":true},"granularity":{"type":"string","enum":["day","week"]},"timezone":{"type":"string"}},"required":["startDate","endDate","granularity","timezone"]}},"required":["totals","breakdownBySource","earningsByType","overTime","averageByDayOfWeek","averageByHourOfDay","period"]},"example":{"totals":{"allTime":{"gross":1250000,"net":1037500},"thisMonth":{"gross":120000,"net":99000,"previousMonthGross":100000,"previousMonthNet":82500,"grossChangePercentage":20,"netChangePercentage":20}},"breakdownBySource":{"subs":{"gross":50000,"net":41250},"messages":{"gross":15000,"net":12375},"posts":{"gross":25000,"net":20625},"tips":{"gross":12000,"net":9900},"referrals":{"gross":4000,"net":3300},"renewals":{"gross":10000,"net":8250},"other":{"gross":4000,"net":3300}},"earningsByType":{"renewals":{"gross":10000,"net":8250},"messages":{"gross":15000,"net":12375},"tips":{"gross":12000,"net":9900},"subs":{"gross":50000,"net":41250}},"overTime":[{"periodStart":"2026-03-01T00:00:00.000Z","gross":24000,"net":19800},{"periodStart":"2026-03-02T00:00:00.000Z","gross":18000,"net":14850}],"averageByDayOfWeek":{"1":11000,"2":9500,"3":10250,"4":9800,"5":12000,"6":8700,"7":9100},"averageByHourOfDay":{"0":0,"1":0,"2":0,"3":0,"4":0,"5":0,"6":0,"7":0,"8":1200,"9":2300,"10":2800,"11":3200,"12":3500,"13":3700,"14":4200,"15":3900,"16":3300,"17":3000,"18":2600,"19":2100,"20":1700,"21":1300,"22":900,"23":400},"period":{"startDate":"2026-03-01T00:00:00.000Z","endDate":"2026-04-01T00:00:00.000Z","granularity":"day","timezone":"UTC"}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination) OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/insights/subscribers":{"get":{"summary":"Get subscriber events over time for a creator","description":"Returns cursor-paginated subscriber event data for the specified creator over a specified time period.\n\nThis endpoint is an analytics time series, not a real-time audience snapshot:\n- `newSubscribersCount` = number of new subscription starts in the period bucket\n- `cancelledSubscribersCount` = number of subscription chain ends in the period bucket\n- `total` = cumulative net change from the beginning of the requested range (`new - cancelled`)\n\nIf you need a current audience count/list (for messaging or contact list UX), use Smart Lists endpoints (`/{creatorUserUuid}/chats/lists/smart` and `/{creatorUserUuid}/chats/lists/smart/{uuid}`) instead of this endpoint.\n\nData is aggregated daily with timezone-aware boundaries. When dates include timezone offsets, results are normalized to midnight in that timezone (expressed as UTC).\n\n<Info>Scopes required: `read:creator`, `read:insights`</Info>","operationId":"getCreatorSubscribers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included. Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included. Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation.","name":"endDate","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination - If given, pass `nextCursor` to get the next page."},"required":false,"description":"Cursor for pagination - If given, pass `nextCursor` to get the next page.","name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20,"description":"Number of items to return per page (1-50, default: 20)"},"required":false,"description":"Number of items to return per page (1-50, default: 20)","name":"size","in":"query"}],"responses":{"200":{"description":"Creator subscribers data with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"Date as UTC ISO 8601 datetime string representing midnight in the requested timezone (e.g., '2024-01-05T23:00:00.000Z' for midnight +01:00)"},"total":{"type":"number","description":"Cumulative net subscriber change from query start date (new - cancelled). This is not an absolute current subscriber snapshot."},"newSubscribersCount":{"type":"number","description":"Number of new subscribers for this period"},"cancelledSubscribersCount":{"type":"number","description":"Number of cancelled subscribers for this period"}},"required":["date","total","newSubscribersCount","cancelledSubscribersCount"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page, null if no more data"}},"required":["data","nextCursor"]},"example":{"data":[{"date":"2024-01-15T00:00:00.000Z","total":56,"newSubscribersCount":45,"cancelledSubscribersCount":12},{"date":"2024-01-14T00:00:00.000Z","total":23,"newSubscribersCount":38,"cancelledSubscribersCount":15}],"nextCursor":"eyJkYXRlIjoiMjAyNC0wMS0xNVQwMDowMDowMC4wMDBaIn0"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination) OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/insights/top-spenders":{"get":{"summary":"Get top-spending fans for a creator","description":"Returns a paginated list of the top-spending fans for the specified creator with their spending totals and message counts.\n\n<Info>Scopes required: `read:creator`, `read:insights`, `read:fan`</Info>","operationId":"getCreatorTopSpenders","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z)."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.","name":"endDate","in":"query"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"Top spending fans with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"gross":{"type":"number","description":"Total amount this fan paid, in USD cents"},"net":{"type":"number","description":"Creator's total cut from this fan after Fanvue fees, in USD cents"},"messages":{"type":"number","description":"Number of messages exchanged with this fan"},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"],"description":"Fan's user information"}},"required":["gross","net","messages","user"]},"description":"Array of top spending fans with their spending totals and message counts"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"gross":15000,"net":12750,"messages":342,"user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}},{"gross":8500,"net":7225,"messages":189,"user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination) OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/media/uploads":{"post":{"summary":"Create multipart upload session for creator","description":"Create a media record for a creator and start an S3 multipart upload session.\n\n    <Info>Scopes required: `write:creator`, `write:media`</Info>","operationId":"createCreatorUploadSession","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"filename":{"type":"string","minLength":1,"maxLength":255},"mediaType":{"type":"string","enum":["image","video","audio","document"]}},"required":["name","filename","mediaType"]}}}},"responses":{"200":{"description":"Upload session created","content":{"application/json":{"schema":{"type":"object","properties":{"mediaUuid":{"type":"string","format":"uuid"},"uploadId":{"type":"string"}},"required":["mediaUuid","uploadId"]},"example":{"mediaUuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","uploadId":"abc123XYZ789multipart"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/media/uploads/{uploadId}/parts/{partNumber}/url":{"get":{"summary":"Get signed URL for upload part","description":"Return a presigned URL to upload a specific part number for creator's media upload session.\n\n    <Info>Scopes required: `write:creator`, `write:media`</Info>","operationId":"getCreatorUploadPartUrl","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string"},"required":true,"name":"uploadId","in":"path"},{"schema":{"type":"number","nullable":true},"required":false,"name":"partNumber","in":"path"}],"responses":{"200":{"description":"Signed URL for part upload","content":{"text/plain":{"schema":{"type":"string","format":"uri"},"example":"https://s3.amazonaws.com/fanvue-uploads/media/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a?partNumber=1&uploadId=abc123XYZ789multipart&X-Amz-Signature=..."}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/media/uploads/{uploadId}":{"patch":{"summary":"Complete creator's upload session","description":"Complete multipart upload in S3 for creator's media and set media status to processing.\n    Media URLs will be available once processing completes.\n\n    <Info>Scopes required: `write:creator`, `write:media`</Info>","operationId":"completeCreatorUploadSession","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string"},"required":true,"name":"uploadId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parts":{"type":"array","items":{"type":"object","properties":{"ETag":{"type":"string"},"PartNumber":{"type":"number"}},"required":["PartNumber"]}}}}}}},"responses":{"200":{"description":"Upload session completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["created","processing","ready","error"]}},"required":["status"]},"example":{"status":"processing"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/posts":{"post":{"summary":"Create a new post for a creator","description":"Create a new post on behalf of a creator with optional media, text, and pricing.\n\n    <Info>Scopes required: `write:post`, `write:creator`</Info>","operationId":"createCreatorPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":5000,"description":"Text content of the post"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs to attach to the post"},"mediaPreviewUuid":{"type":"string","format":"uuid","description":"UUID of free preview media shown before unlock"},"price":{"type":"number","minimum":300,"description":"Price in cents for paid posts (requires media)"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","format":"date-time","description":"Future date/time to publish the post (ISO 8601 format)"},"expiresAt":{"type":"string","format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"collectionUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of content collection UUIDs to assign to the post"}},"required":["audience"]}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the created post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Check out my latest content!","price":999,"mediaPreviewUuid":"f1e2d3c4-b5a6-4789-8123-456789abcdef","audience":"subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":"2025-01-01T12:00:00.000Z"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/posts/{uuid}":{"patch":{"summary":"Update a post for a creator","description":"Update an existing post on behalf of a creator. All fields are optional — only provided fields will be updated.\n\n    If a scheduled post has its `publishAt` set to `null`, it will be published immediately.\n\n    <Info>Scopes required: `write:post`, `write:creator`</Info>","operationId":"updateCreatorPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to update"},"required":true,"description":"UUID of the post to update","name":"uuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","nullable":true,"maxLength":5000,"description":"Text content of the post. Set to null to remove text."},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs to attach to the post (replaces existing media)"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media shown before unlock. Set to null to remove."},"price":{"type":"number","nullable":true,"minimum":300,"description":"Price in cents for paid posts. Set to null to make the post free."},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time to publish the post (ISO 8601 format). Set to null to publish immediately if currently scheduled."},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format). Set to null to remove expiration."},"collectionUuids":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Array of content collection UUIDs to assign to the post (replaces existing collections). Set to null to remove all collections."}}}}}},"responses":{"200":{"description":"Post updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Updated post content!","price":null,"audience":"followers-and-subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":true,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[{"uuid":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","label":"Behind the Scenes"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"delete":{"summary":"Delete a post for a creator","description":"Soft-delete an existing post on behalf of a creator.\n\n    <Info>Scopes required: `write:post`, `write:creator`</Info>","operationId":"deleteCreatorPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to delete"},"required":true,"description":"UUID of the post to delete","name":"uuid","in":"path"}],"responses":{"204":{"description":"Post deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/posts/{uuid}/repost":{"post":{"summary":"Repost content for a creator","description":"Re-surface an existing post on behalf of a creator by updating its publication date to now. This moves the post back to the top of the feed.\n\n    <Info>Scopes required: `write:post`, `write:creator`</Info>","operationId":"repostCreatorPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to repost"},"required":true,"description":"UUID of the post to repost","name":"uuid","in":"path"}],"responses":{"200":{"description":"Post reposted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Check out my latest content!","price":null,"audience":"subscribers","publishAt":null,"publishedAt":"2025-03-15T14:30:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":false,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/posts/{uuid}/pin":{"post":{"summary":"Pin a post for a creator","description":"Pin a post on behalf of a creator so it appears at the top of the feed.\n\n    <Info>Scopes required: `write:post`, `write:creator`</Info>","operationId":"pinCreatorPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to pin"},"required":true,"description":"UUID of the post to pin","name":"uuid","in":"path"}],"responses":{"200":{"description":"Post pinned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Updated post content!","price":null,"audience":"followers-and-subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":true,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[{"uuid":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","label":"Behind the Scenes"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"delete":{"summary":"Unpin a post for a creator","description":"Unpin a post on behalf of a creator so it returns to normal feed ordering.\n\n    <Info>Scopes required: `write:post`, `write:creator`</Info>","operationId":"unpinCreatorPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to unpin"},"required":true,"description":"UUID of the post to unpin","name":"uuid","in":"path"}],"responses":{"200":{"description":"Post unpinned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Updated post content!","price":null,"audience":"followers-and-subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":true,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[{"uuid":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","label":"Behind the Scenes"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/posts/{uuid}/comments":{"post":{"summary":"Create a comment on a post for a creator","description":"Create a new comment on a specific post on behalf of a creator.\n\n    <Info>Scopes required: `write:post`, `write:creator`</Info>","operationId":"createCreatorPostComment","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to comment on"},"required":true,"description":"UUID of the post to comment on","name":"uuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":600,"description":"Comment text content (1–600 characters)"}},"required":["text"]}}}},"responses":{"201":{"description":"Comment created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the created comment"},"text":{"type":"string","description":"Comment text content"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the comment was created (ISO 8601 format)"},"updatedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the comment was last updated (ISO 8601 format)"}},"required":["uuid","text","createdAt","updatedAt"]},"example":{"uuid":"550e8400-e29b-41d4-a716-446655440001","text":"Thanks for the kind words!","createdAt":"2025-01-15T10:30:00.000Z","updatedAt":null}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"get":{"summary":"Get comments on a creator's post","description":"Returns a paginated list of comments on a specific post on behalf of a creator. The creator must own the post.\n\n    <Info>Scopes required: `read:post`, `read:creator`</Info>","operationId":"getCreatorPostComments","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to retrieve comments for"},"required":true,"description":"UUID of the post to retrieve comments for","name":"uuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of comments on this post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the comment"},"text":{"type":"string","description":"Comment text content"},"user":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"}},"required":["uuid","handle","displayName","nickname","isTopSpender"],"description":"User who created the comment (null if user was deleted)"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the comment was created (ISO 8601 format)"},"updatedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the comment was last updated (ISO 8601 format)"}},"required":["uuid","text","user","createdAt","updatedAt"]},"description":"Array of comments on this post"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"550e8400-e29b-41d4-a716-446655440001","text":"Great content! Thanks for sharing!","user":{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","handle":"sarah","displayName":"Sarah Johnson","nickname":null,"isTopSpender":true},"createdAt":"2024-01-15T10:30:00.000Z","updatedAt":"2024-01-15T10:30:00.000Z"},{"uuid":"550e8400-e29b-41d4-a716-446655440002","text":"Love this post!","user":{"uuid":"b2c3d4e5-f678-90ab-cdef-123456789012","handle":"mike","displayName":"Mike Smith","nickname":null,"isTopSpender":false},"createdAt":"2024-01-15T09:15:00.000Z","updatedAt":"2024-01-15T09:15:00.000Z"},{"uuid":"550e8400-e29b-41d4-a716-446655440003","text":"[Comment from deleted user]","user":null,"createdAt":"2024-01-14T18:00:00.000Z","updatedAt":"2024-01-14T18:00:00.000Z"}],"pagination":{"page":1,"size":2,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/posts/{uuid}/comments/{commentUuid}":{"delete":{"summary":"Delete a comment from a post for a creator","description":"Delete a comment from a post on behalf of a creator. The comment can be deleted if the creator is either the comment author or the post owner.\n\n    <Info>Scopes required: `write:post`, `write:creator`</Info>","operationId":"deleteCreatorPostComment","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post"},"required":true,"description":"UUID of the post","name":"uuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the comment to delete"},"required":true,"description":"UUID of the comment to delete","name":"commentUuid","in":"path"}],"responses":{"204":{"description":"Comment deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/lists/smart":{"get":{"summary":"Get creator's smart lists","description":"Get all available smart lists for a specific creator with member counts.\n\nSmart lists are system-generated dynamic audience segments (not user-created lists). They are computed from relationship/subscription/payment state and update automatically.\n\nExamples include:\n- `subscribers`\n- `followers`\n- `auto_renewing`\n- `non_renewing`\n- `expired_subscribers`\n- `free_trial_subscribers`\n- `spent_more_than_50`\n\nFor `subscribers`, the count reflects current non-deleted subscription relationships that are contactable by the requested creator.\n\n<Info>Scopes required: `read:creator` `read:chat` `read:fan`</Info>","operationId":"getCreatorSmartLists","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"responses":{"200":{"description":"List of smart lists","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the smart list"},"uuid":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"],"description":"Smart list unique identifier"},"count":{"type":"number","description":"Number of members in this list"}},"required":["name","uuid","count"]}},"example":[{"name":"Subscribers","uuid":"subscribers","count":1250},{"name":"Auto-renewing","uuid":"auto_renewing","count":892},{"name":"Non-renewing","uuid":"non_renewing","count":358},{"name":"Followers","uuid":"followers","count":2156},{"name":"Free trial subscribers","uuid":"free_trial_subscribers","count":45},{"name":"Expired subscribers","uuid":"expired_subscribers","count":178},{"name":"Spent more than $50","uuid":"spent_more_than_50","count":423},{"name":"Muted","uuid":"muted","count":12}]}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/lists/smart/{uuid}":{"get":{"summary":"Get creator's smart list members","description":"Get members of a specific smart list for a creator with pagination.\n\nSmart lists are system-generated dynamic audience segments (not user-created lists). The returned members are filtered by contactability and the selected smart list type.\n\n<Info>Scopes required: `read:creator` `read:chat` `read:fan`</Info>","operationId":"getCreatorSmartListMembers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted"],"description":"Smart list unique identifier"},"required":true,"description":"Smart list unique identifier","name":"uuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"Smart list members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"User UUID"},"displayName":{"type":"string","description":"User's display name"},"handle":{"type":"string","description":"User's handle"},"isCreator":{"type":"boolean","description":"Whether user is a creator"}},"required":["uuid","displayName","handle","isCreator"]},"description":"Members of the smart list"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"550e8400-e29b-41d4-a716-446655440000","displayName":"Sarah Johnson","handle":"sarah_j","isCreator":false},{"uuid":"550e8400-e29b-41d4-a716-446655440001","displayName":"Mike Chen","handle":"mike_creates","isCreator":true},{"uuid":"550e8400-e29b-41d4-a716-446655440002","displayName":"Alex Rivera","handle":"alexr","isCreator":false}],"pagination":{"page":1,"size":20,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/lists/custom":{"get":{"summary":"Get creator's custom lists","description":"Get a creator's custom lists with member counts. Supports pagination.\n\n<Info>Scopes required: `read:creator` `read:chat` `read:fan`</Info>","operationId":"getCreatorCustomLists","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of custom lists","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Custom list UUID"},"name":{"type":"string","description":"Custom list name"},"membersCount":{"type":"number","description":"Number of members in this list"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the list was created"}},"required":["uuid","name","membersCount","createdAt"]},"description":"Array of custom lists"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"123e4567-e89b-12d3-a456-426614174000","name":"VIP Subscribers","membersCount":47,"createdAt":"2024-01-15T10:30:00Z"},{"uuid":"123e4567-e89b-12d3-a456-426614174001","name":"New Followers","membersCount":128,"createdAt":"2024-02-20T09:15:00Z"},{"uuid":"123e4567-e89b-12d3-a456-426614174002","name":"Content Collaborators","membersCount":23,"createdAt":"2024-01-08T11:20:00Z"}],"pagination":{"page":1,"size":20,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/chats/lists/custom/{uuid}":{"get":{"summary":"Get creator's custom list members","description":"Get members of a specific custom list for a creator with pagination.\n\n<Info>Scopes required: `read:creator` `read:chat` `read:fan`</Info>","operationId":"getCreatorCustomListMembers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"Custom list members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"User UUID"},"displayName":{"type":"string","description":"User's display name"},"handle":{"type":"string","description":"User's handle"},"isCreator":{"type":"boolean","description":"Whether user is a creator"}},"required":["uuid","displayName","handle","isCreator"]},"description":"Members of the custom list"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","displayName":"Emma Thompson","handle":"emma_art","isCreator":true},{"uuid":"6ba7b811-9dad-11d1-80b4-00c04fd430c8","displayName":"Jake Martinez","handle":"jakethefan","isCreator":false},{"uuid":"6ba7b812-9dad-11d1-80b4-00c04fd430c8","displayName":"Sophie Williams","handle":"sophie_w","isCreator":true},{"uuid":"6ba7b813-9dad-11d1-80b4-00c04fd430c8","displayName":"David Kim","handle":"davidk_collector","isCreator":false}],"pagination":{"page":1,"size":20,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"description":"Custom list not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/tracking-links":{"get":{"summary":"List creator's tracking links","description":"List tracking links for the specified creator with cursor-based pagination.\n\n<Info>Scope required: `read:tracking_links` `read:creator`</Info>","operationId":"listCreatorTrackingLinks","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of results to return (default 20)"},"required":false,"description":"Number of results to return (default 20)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"description":"Cursor for pagination","name":"cursor","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter links created on or after this ISO datetime"},"required":false,"description":"Filter links created on or after this ISO datetime","name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter links created before this ISO datetime"},"required":false,"description":"Filter links created before this ISO datetime","name":"createdBefore","in":"query"}],"responses":{"200":{"description":"List of tracking links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Tracking link UUID"},"name":{"type":"string","description":"Name of the tracking link"},"linkUrl":{"type":"string","description":"Tracking link URL (e.g., 'fv-123')"},"externalSocialPlatform":{"type":"string","enum":["facebook","instagram","other","reddit","snapchat","tiktok","twitter","youtube"],"description":"Social platform"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"},"clicks":{"type":"number","description":"Number of clicks on this link"},"engagement":{"type":"object","properties":{"acquiredSubscribers":{"type":"number","description":"Number of subscribers acquired through this link (first-click attribution - users only counted for the first link they clicked)"},"acquiredFollowers":{"type":"number","description":"Number of followers acquired through this link (first-click attribution - users only counted for the first link they clicked)"},"totalSubscribers":{"type":"number","description":"Total count of all users who clicked this link and are currently active subscribers"},"totalFollowers":{"type":"number","description":"Total count of all users who clicked this link and are currently followers"}},"required":["acquiredSubscribers","acquiredFollowers","totalSubscribers","totalFollowers"],"description":"Engagement metrics from this tracking link"},"earnings":{"type":"object","nullable":true,"properties":{"totalGross":{"type":"number","description":"Total gross earnings from this link (before fees)"},"totalNet":{"type":"number","description":"Total net earnings from this link (after fees)"}},"required":["totalGross","totalNet"],"description":"Earnings from this tracking link (null for newly created links)"}},"required":["uuid","name","linkUrl","externalSocialPlatform","createdAt","clicks","engagement","earnings"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page"}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"d4e5f6g7-8h9i-0j1k-2l3m-n4o5p6q7r8s9","name":"TikTok Profile","linkUrl":"fv-123456","externalSocialPlatform":"tiktok","createdAt":"2024-01-15T00:00:00.000Z","clicks":342,"engagement":{"acquiredSubscribers":28,"acquiredFollowers":15,"totalSubscribers":35,"totalFollowers":20},"earnings":{"totalGross":150000,"totalNet":120000}},{"uuid":"e5f6g7h8-9i0j-1k2l-3m4n-o5p6q7r8s9t0","name":"Instagram Bio","linkUrl":"fv-789012","externalSocialPlatform":"instagram","createdAt":"2024-01-14T00:00:00.000Z","clicks":156,"engagement":{"acquiredSubscribers":12,"acquiredFollowers":8,"totalSubscribers":18,"totalFollowers":12},"earnings":{"totalGross":75000,"totalNet":60000}}],"nextCursor":"eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE0VDAwOjAwOjAwLjAwMFoifQ=="}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"post":{"summary":"Create a tracking link for a creator","description":"Create a new tracking link for the specified creator.\n\n<Info>Scope required: `write:tracking_links` `write:creator`</Info>","operationId":"createCreatorTrackingLink","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the tracking link"},"externalSocialPlatform":{"type":"string","enum":["facebook","instagram","other","reddit","snapchat","tiktok","twitter","youtube"],"description":"Social platform"}},"required":["name","externalSocialPlatform"]}}}},"responses":{"201":{"description":"Tracking link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Tracking link UUID"},"name":{"type":"string","description":"Name of the tracking link"},"linkUrl":{"type":"string","description":"Tracking link URL (e.g., 'fv-123')"},"externalSocialPlatform":{"type":"string","enum":["facebook","instagram","other","reddit","snapchat","tiktok","twitter","youtube"],"description":"Social platform"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"},"clicks":{"type":"number","description":"Number of clicks on this link"},"engagement":{"type":"object","properties":{"acquiredSubscribers":{"type":"number","description":"Number of subscribers acquired through this link (first-click attribution - users only counted for the first link they clicked)"},"acquiredFollowers":{"type":"number","description":"Number of followers acquired through this link (first-click attribution - users only counted for the first link they clicked)"},"totalSubscribers":{"type":"number","description":"Total count of all users who clicked this link and are currently active subscribers"},"totalFollowers":{"type":"number","description":"Total count of all users who clicked this link and are currently followers"}},"required":["acquiredSubscribers","acquiredFollowers","totalSubscribers","totalFollowers"],"description":"Engagement metrics from this tracking link"},"earnings":{"type":"object","nullable":true,"properties":{"totalGross":{"type":"number","description":"Total gross earnings from this link (before fees)"},"totalNet":{"type":"number","description":"Total net earnings from this link (after fees)"}},"required":["totalGross","totalNet"],"description":"Earnings from this tracking link (null for newly created links)"}},"required":["uuid","name","linkUrl","externalSocialPlatform","createdAt","clicks","engagement","earnings"]},"example":{"uuid":"d4e5f6g7-8h9i-0j1k-2l3m-n4o5p6q7r8s9","name":"TikTok Profile","linkUrl":"fv-123456","externalSocialPlatform":"tiktok","createdAt":"2024-01-15T00:00:00.000Z","clicks":0,"engagement":{"acquiredSubscribers":0,"acquiredFollowers":0,"totalSubscribers":0,"totalFollowers":0},"earnings":null}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/tracking-links/{uuid}/users":{"get":{"summary":"List users for a creator's tracking link","description":"List users associated with a tracking link for the specified creator with cursor-based pagination.\n\n<Info>Scope required: `read:tracking_links` `read:creator`</Info>","operationId":"listCreatorTrackingLinkUsers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Tracking link UUID"},"required":true,"description":"Tracking link UUID","name":"uuid","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of results to return (default 20)"},"required":false,"description":"Number of results to return (default 20)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"description":"Cursor for pagination","name":"cursor","in":"query"}],"responses":{"200":{"description":"List of users associated with the tracking link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"},"status":{"type":"string","nullable":true,"enum":["subscriber","follower","expired","deleted"],"description":"User's relationship status with the creator: subscriber (active subscription), follower (following only), expired (subscription ended), deleted (user soft-deleted), or null (registered via link but no current relationship)"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt","status"]},"description":"Users associated with this tracking link"},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page"}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","displayName":"Sarah Jones","nickname":"SarahK","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/fan-a.jpg","registeredAt":"2024-01-15T00:00:00.000Z","status":"subscriber"},{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","displayName":"Mike Smithly","nickname":null,"isTopSpender":false,"avatarUrl":null,"registeredAt":"2024-01-14T00:00:00.000Z","status":"follower"}],"nextCursor":"456"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/tracking-links/{uuid}/users/{userUuid}/metadata":{"get":{"summary":"Get tracking metadata for a user on a creator's tracking link","description":"Get the custom tracking metadata from a user's most recent impression on a tracking link for the specified creator.\n\n<Info>Scope required: `read:tracking_links` `read:creator`</Info>","operationId":"getCreatorUserTrackingMetadata","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Tracking link UUID"},"required":true,"description":"Tracking link UUID","name":"uuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"User UUID"},"required":true,"description":"User UUID","name":"userUuid","in":"path"}],"responses":{"200":{"description":"User's tracking metadata","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Custom metadata from the user's most recent impression on this link"}},"required":["metadata"]},"example":{"metadata":{"lead_id":"xyz123","source":"snapchat","conversation_id":"abc456"}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/tracking-links/{uuid}":{"delete":{"summary":"Delete a tracking link for a creator","description":"Delete a tracking link for the specified creator.\n\n<Info>Scope required: `write:tracking_links` `write:creator`</Info>","operationId":"deleteCreatorTrackingLink","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Tracking link UUID"},"required":true,"description":"Tracking link UUID","name":"uuid","in":"path"}],"responses":{"204":{"description":"Tracking link deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/subscribers/online":{"get":{"summary":"Get online subscribers","description":"Returns subscribers who are currently online for the specified creator.\n\nIf `subscriberUuids` query parameter is provided, filters to only those specific subscribers.\nOtherwise returns all online subscribers up to `limit`.\n\n<Info>Scopes required: `read:creator`, `read:fan`</Info>","operationId":"getOnlineSubscribers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":1000,"description":"Maximum number of subscribers to return"},"required":false,"description":"Maximum number of subscribers to return","name":"limit","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of subscriber UUIDs to filter (optional)"},"required":false,"description":"Comma-separated list of subscriber UUIDs to filter (optional)","name":"subscriberUuids","in":"query"}],"responses":{"200":{"description":"List of online subscribers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Subscriber's unique identifier"},"lastSeenAt":{"type":"string","nullable":true,"format":"date-time","description":"When the subscriber was last seen online"}},"required":["uuid","lastSeenAt"]},"description":"List of online subscribers"},"count":{"type":"number","description":"Total number of online subscribers returned"}},"required":["data","count"]},"example":{"data":[{"uuid":"550e8400-e29b-41d4-a716-446655440000","lastSeenAt":"2024-01-15T10:30:00.000Z"},{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","lastSeenAt":"2024-01-15T10:28:00.000Z"}],"count":2}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/vault/folders":{"post":{"summary":"Create a creator vault folder","description":"Create a new folder in the specified creator's vault.\n\n<Info>Scopes required: `write:creator`, `write:media`</Info>","operationId":"createCreatorVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Name for the new folder"}},"required":["name"]}}}},"responses":{"201":{"description":"Folder created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Folder name"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the folder was created"},"mediaCount":{"type":"number","description":"Number of media items in the folder"}},"required":["name","createdAt","mediaCount"]},"example":{"name":"My Photos","createdAt":"2025-01-15T10:30:00.000Z","mediaCount":0}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"409":{"description":"Folder with this name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"get":{"summary":"List creator vault folders","description":"Returns a paginated list of folders in the specified creator's vault.\n\n<Info>Scopes required: `read:creator`, `read:media`</Info>","operationId":"listCreatorVaultFolders","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"responses":{"200":{"description":"List of vault folders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Folder name"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the folder was created"},"mediaCount":{"type":"number","description":"Number of media items in the folder"}},"required":["name","createdAt","mediaCount"]},"description":"Array of vault folders"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"name":"My Photos","createdAt":"2025-01-15T10:30:00.000Z","mediaCount":42},{"name":"Videos","createdAt":"2025-01-16T14:20:00.000Z","mediaCount":15}],"pagination":{"page":1,"size":20,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/vault/folders/{folderName}":{"get":{"summary":"Get creator vault folder details","description":"Returns details of a specific creator vault folder by name.\n\n<Info>Scopes required: `read:creator`, `read:media`</Info>","operationId":"getCreatorVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"}],"responses":{"200":{"description":"Folder details","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Folder name"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the folder was created"},"mediaCount":{"type":"number","description":"Number of media items in the folder"}},"required":["name","createdAt","mediaCount"]},"example":{"name":"My Photos","createdAt":"2025-01-15T10:30:00.000Z","mediaCount":42}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"patch":{"summary":"Rename creator vault folder","description":"Rename an existing folder in the specified creator's vault.\n\n<Info>Scopes required: `write:creator`, `write:media`</Info>","operationId":"renameCreatorVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"New name for the folder"}},"required":["name"]}}}},"responses":{"204":{"description":"Folder renamed successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"409":{"description":"Folder with the new name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"delete":{"summary":"Delete creator vault folder","description":"Delete a folder from the specified creator's vault.\nMedia items in the folder will be detached but not deleted.\n\n<Info>Scopes required: `write:creator`, `write:media`</Info>","operationId":"deleteCreatorVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"}],"responses":{"204":{"description":"Folder deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/vault/folders/{folderName}/media":{"get":{"summary":"List media in creator vault folder","description":"Returns a paginated list of media items in the specified creator folder.\n\n<Info>Scopes required: `read:creator`, `read:media`</Info>","operationId":"listCreatorVaultFolderMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of media in folder","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"createdAt":{"type":"string","nullable":true,"format":"date"},"mediaType":{"type":"string"}},"required":["uuid","name","createdAt","mediaType"]},"description":"Array of media items"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"550e8400-e29b-41d4-a716-446655440000","name":"photo1.jpg","createdAt":"2025-01-15T10:30:00.000Z","mediaType":"image"},{"uuid":"550e8400-e29b-41d4-a716-446655440001","name":"video1.mp4","createdAt":"2025-01-16T14:20:00.000Z","mediaType":"video"}],"pagination":{"page":1,"size":20,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"post":{"summary":"Add media to creator vault folder","description":"Add one or more media items to the specified creator folder.\nMedia items must belong to the creator.\n\n<Info>Scopes required: `write:creator`, `write:media`</Info>","operationId":"attachCreatorVaultMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"UUIDs of media items to attach to the folder"}},"required":["mediaUuids"]}}}},"responses":{"201":{"description":"Media added to folder","content":{"application/json":{"schema":{"type":"object","properties":{"addedCount":{"type":"number","description":"Number of media items successfully added"}},"required":["addedCount"]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/vault/folders/{folderName}/media/{mediaUuid}":{"delete":{"summary":"Remove media from creator vault folder","description":"Remove a media item from the specified creator folder.\nThe media item itself is not deleted, only the folder association.\n\n<Info>Scopes required: `write:creator`, `write:media`</Info>","operationId":"detachCreatorVaultMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"mediaUuid","in":"path"}],"responses":{"204":{"description":"Media removed from folder"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/followers":{"get":{"summary":"Get followers","description":"Returns a paginated list of users who follow the authenticated user, excluding those with active subscriptions to avoid duplication.\n\n    <Info>Scope required: `read:fan`</Info>","operationId":"listFollowers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of followers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"description":"Array of followers"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"},{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/insights/earnings":{"get":{"summary":"Get earnings data","description":"Returns cursor-paginated invoice data for the authenticated creator over a specified time period. Each transaction includes information about the fan who made the payment.\n\n<Info>Scope required: `read:insights`</Info>","operationId":"getEarnings","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z)."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EarningSource"},"description":"Comma-separated list of earning sources"},"required":false,"description":"Comma-separated list of earning sources. Default: all","name":"source","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Cursor for pagination - If given, pass `nextCursor` to get the next page."},"required":false,"description":"Cursor for pagination - If given, pass `nextCursor` to get the next page.","name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20,"description":"Number of items to return per page (1-50, default: 20)"},"required":false,"description":"Number of items to return per page (1-50, default: 20)","name":"size","in":"query"}],"responses":{"200":{"description":"Earnings data with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Payment date as UTC ISO 8601 datetime string"},"gross":{"type":"number","description":"Amount the fan paid, converted to USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"},"currency":{"type":"string","nullable":true,"description":"Informational only — the local currency the fan originally paid in (e.g. 'BRL'). The gross and net amounts are already converted to USD cents regardless of this value."},"source":{"$ref":"#/components/schemas/EarningSource"},"transactionOrderId":{"type":"string","description":"Transaction order ID"},"transactionOrderStatus":{"type":"string","enum":["availableForPayout","pendingBalance"],"description":"Transaction order status"},"messageUuid":{"type":"string","format":"uuid","description":"Message UUID when source is message (e.g. paid chat or broadcast message)"},"postUuid":{"type":"string","format":"uuid","description":"Post UUID when source is post"},"user":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"}},"required":["uuid","handle","displayName","nickname","isTopSpender"],"description":"Fan's user information (null for transactions without a fan like referrals, affiliates)"}},"required":["date","gross","net","currency","source","transactionOrderId","transactionOrderStatus","user"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page, null if no more data"}},"required":["data","nextCursor"]},"example":{"data":[{"date":"2024-01-15T00:00:00.000Z","gross":5000,"net":4250,"currency":"USD","source":"subscription","transactionOrderId":"FV-ORDER-123","transactionOrderStatus":"availableForPayout","user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}},{"date":"2024-01-14T00:00:00.000Z","gross":2500,"net":2125,"currency":"USD","source":"tip","transactionOrderId":"FV-ORDER-124","transactionOrderStatus":"pendingBalance","user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}}],"nextCursor":"eyJkYXRlIjoiMjAyNC0wMS0xNVQwMDowMDowMC4wMDBaIn0"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/insights/earnings/summary":{"get":{"summary":"Get aggregated earnings summary","description":"Returns pre-aggregated earnings metrics for the authenticated creator, including all-time totals, month-over-month comparisons, source/type breakdowns, chart series, and averages.\n\n<Info>Scope required: `read:insights`</Info>","operationId":"getEarningsSummary","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z)."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.","name":"endDate","in":"query"},{"schema":{"type":"string","enum":["day","week"],"default":"day","description":"Aggregation granularity for the over-time chart"},"required":false,"description":"Aggregation granularity for the over-time chart","name":"granularity","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA timezone used for period grouping and month boundaries (e.g., Europe/London, America/New_York)"},"required":false,"description":"IANA timezone used for period grouping and month boundaries (e.g., Europe/London, America/New_York)","name":"timezone","in":"query"}],"responses":{"200":{"description":"Aggregated earnings summary","content":{"application/json":{"schema":{"type":"object","properties":{"totals":{"type":"object","properties":{"allTime":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"thisMonth":{"type":"object","properties":{"gross":{"type":"number"},"net":{"type":"number"},"previousMonthGross":{"type":"number"},"previousMonthNet":{"type":"number"},"grossChangePercentage":{"type":"number","nullable":true},"netChangePercentage":{"type":"number","nullable":true}},"required":["gross","net","previousMonthGross","previousMonthNet","grossChangePercentage","netChangePercentage"]}},"required":["allTime","thisMonth"]},"breakdownBySource":{"type":"object","properties":{"subs":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"messages":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"posts":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"tips":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"referrals":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"renewals":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"other":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]}},"required":["subs","messages","posts","tips","referrals","renewals","other"]},"earningsByType":{"type":"object","properties":{"renewals":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"messages":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"tips":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]},"subs":{"type":"object","properties":{"gross":{"type":"number","description":"Amount the fan paid, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees, in USD cents"}},"required":["gross","net"]}},"required":["renewals","messages","tips","subs"]},"overTime":{"type":"array","items":{"type":"object","properties":{"periodStart":{"type":"string","format":"date-time","description":"Start of the aggregation bucket in ISO 8601 with timezone offset"},"gross":{"type":"number","description":"Amount fans paid in this bucket, in USD cents"},"net":{"type":"number","description":"Creator's cut after Fanvue fees in this bucket, in USD cents"}},"required":["periodStart","gross","net"]}},"averageByDayOfWeek":{"type":"object","properties":{"1":{"type":"number"},"2":{"type":"number"},"3":{"type":"number"},"4":{"type":"number"},"5":{"type":"number"},"6":{"type":"number"},"7":{"type":"number"}},"required":["1","2","3","4","5","6","7"],"description":"Average gross earnings by ISO day-of-week (1=Monday, 7=Sunday)"},"averageByHourOfDay":{"type":"object","additionalProperties":{"type":"number"},"description":"Average gross earnings by hour-of-day in the selected timezone (0-23)"},"period":{"type":"object","properties":{"startDate":{"type":"string","nullable":true},"endDate":{"type":"string","nullable":true},"granularity":{"type":"string","enum":["day","week"]},"timezone":{"type":"string"}},"required":["startDate","endDate","granularity","timezone"]}},"required":["totals","breakdownBySource","earningsByType","overTime","averageByDayOfWeek","averageByHourOfDay","period"]},"example":{"totals":{"allTime":{"gross":1250000,"net":1037500},"thisMonth":{"gross":120000,"net":99000,"previousMonthGross":100000,"previousMonthNet":82500,"grossChangePercentage":20,"netChangePercentage":20}},"breakdownBySource":{"subs":{"gross":50000,"net":41250},"messages":{"gross":15000,"net":12375},"posts":{"gross":25000,"net":20625},"tips":{"gross":12000,"net":9900},"referrals":{"gross":4000,"net":3300},"renewals":{"gross":10000,"net":8250},"other":{"gross":4000,"net":3300}},"earningsByType":{"renewals":{"gross":10000,"net":8250},"messages":{"gross":15000,"net":12375},"tips":{"gross":12000,"net":9900},"subs":{"gross":50000,"net":41250}},"overTime":[{"periodStart":"2026-03-01T00:00:00.000Z","gross":24000,"net":19800},{"periodStart":"2026-03-02T00:00:00.000Z","gross":18000,"net":14850}],"averageByDayOfWeek":{"1":11000,"2":9500,"3":10250,"4":9800,"5":12000,"6":8700,"7":9100},"averageByHourOfDay":{"0":0,"1":0,"2":0,"3":0,"4":0,"5":0,"6":0,"7":0,"8":1200,"9":2300,"10":2800,"11":3200,"12":3500,"13":3700,"14":4200,"15":3900,"16":3300,"17":3000,"18":2600,"19":2100,"20":1700,"21":1300,"22":900,"23":400},"period":{"startDate":"2026-03-01T00:00:00.000Z","endDate":"2026-04-01T00:00:00.000Z","granularity":"day","timezone":"UTC"}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/insights/spending":{"get":{"summary":"Get spending reversal data","description":"Returns cursor-paginated reversal invoice data for the authenticated creator over a specified time period. Includes refund and chargeback transactions.\n\n<Info>Scope required: `read:insights`</Info>","operationId":"getSpending","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z)."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SpendingType"},"description":"Comma-separated list of spending sources"},"required":false,"description":"Comma-separated list of spending sources. Default: all","name":"source","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Cursor for pagination - If given, pass `nextCursor` to get the next page."},"required":false,"description":"Cursor for pagination - If given, pass `nextCursor` to get the next page.","name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20,"description":"Number of items to return per page (1-50, default: 20)"},"required":false,"description":"Number of items to return per page (1-50, default: 20)","name":"size","in":"query"}],"responses":{"200":{"description":"Spending reversal data with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Payment date as UTC ISO 8601 datetime string"},"gross":{"type":"number","description":"Amount the fan originally paid, converted to USD cents"},"net":{"type":"number","description":"Creator's reversal (refund/chargeback) impact after Fanvue fees, in USD cents"},"currency":{"type":"string","nullable":true,"description":"Informational only — the local currency the fan originally paid in (e.g. 'BRL'). The gross and net amounts are already converted to USD cents regardless of this value."},"source":{"$ref":"#/components/schemas/SpendingSource"},"messageUuid":{"type":"string","format":"uuid","description":"Message UUID when the reversed payment was a message transaction"},"postUuid":{"type":"string","format":"uuid","description":"Post UUID when the reversed payment was a post"},"user":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"}},"required":["uuid","handle","displayName","nickname","isTopSpender"],"description":"Fan's user information (null for transactions without a fan like referrals, affiliates)"}},"required":["date","gross","net","currency","source","user"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page, null if no more data"}},"required":["data","nextCursor"]},"example":{"data":[{"date":"2024-01-15T00:00:00.000Z","gross":-5000,"net":-4250,"currency":"USD","source":"refund","user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}},{"date":"2024-01-14T00:00:00.000Z","gross":-2500,"net":-2125,"currency":"USD","source":"chargeback","user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}}],"nextCursor":"eyJkYXRlIjoiMjAyNC0wMS0xNVQwMDowMDowMC4wMDBaIn0"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/insights/subscribers":{"get":{"summary":"Get subscriber events over time","description":"Returns cursor-paginated subscriber event data for the authenticated creator over a specified time period.\n\nThis endpoint is an analytics time series, not a real-time audience snapshot:\n- `newSubscribersCount` = number of new subscription starts in the period bucket\n- `cancelledSubscribersCount` = number of subscription chain ends in the period bucket\n- `total` = cumulative net change from the beginning of the requested range (`new - cancelled`)\n\nIf you need a current audience count/list (for messaging or contact list UX), use Smart Lists endpoints (`/chats/lists/smart` and `/chats/lists/smart/{uuid}`) instead of this endpoint.\n\nData is aggregated daily with timezone-aware boundaries. When dates include timezone offsets, results are normalized to midnight in that timezone (expressed as UTC).\n\n<Info>Scope required: `read:insights`</Info>","operationId":"getSubscribers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included. Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included. Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation.","name":"endDate","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination - If given, pass `nextCursor` to get the next page."},"required":false,"description":"Cursor for pagination - If given, pass `nextCursor` to get the next page.","name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20,"description":"Number of items to return per page (1-50, default: 20)"},"required":false,"description":"Number of items to return per page (1-50, default: 20)","name":"size","in":"query"}],"responses":{"200":{"description":"Subscribers data with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"Date as UTC ISO 8601 datetime string representing midnight in the requested timezone (e.g., '2024-01-05T23:00:00.000Z' for midnight +01:00)"},"total":{"type":"number","description":"Cumulative net subscriber change from query start date (new - cancelled). This is not an absolute current subscriber snapshot."},"newSubscribersCount":{"type":"number","description":"Number of new subscribers for this period"},"cancelledSubscribersCount":{"type":"number","description":"Number of cancelled subscribers for this period"}},"required":["date","total","newSubscribersCount","cancelledSubscribersCount"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page, null if no more data"}},"required":["data","nextCursor"]},"example":{"data":[{"date":"2024-01-15T00:00:00.000Z","total":56,"newSubscribersCount":45,"cancelledSubscribersCount":12},{"date":"2024-01-14T00:00:00.000Z","total":23,"newSubscribersCount":38,"cancelledSubscribersCount":15}],"nextCursor":"eyJkYXRlIjoiMjAyNC0wMS0xNVQwMDowMDowMC4wMDBaIn0"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/insights/top-spenders":{"get":{"summary":"Get top-spending fans","description":"Returns a paginated list of the top-spending fans for the authenticated creator with their spending totals and message counts.\n\n<Info>Scopes required: `read:insights`, `read:fan`</Info>","operationId":"getTopSpenders","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z)."},"required":false,"description":"Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included."},"required":false,"description":"End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.","name":"endDate","in":"query"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"Top spending fans with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"gross":{"type":"number","description":"Total amount this fan paid, in USD cents"},"net":{"type":"number","description":"Creator's total cut from this fan after Fanvue fees, in USD cents"},"messages":{"type":"number","description":"Number of messages exchanged with this fan"},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"],"description":"Fan's user information"}},"required":["gross","net","messages","user"]},"description":"Array of top spending fans with their spending totals and message counts"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"gross":15000,"net":12750,"messages":342,"user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}},{"gross":8500,"net":7225,"messages":189,"user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"}}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/insights/fans":{"get":{"summary":"Get fan insights in bulk","description":"Returns detailed insights for multiple fans in a single request.\n\nThis endpoint is optimized for chat list screens that need to hydrate fan insights without per-fan round trips.\n\n<Info>Scopes required: `read:insights`, `read:fan`</Info>\n\n<Note>Maximum 20 fan UUIDs per request.</Note>","operationId":"getBulkFanInsights","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","description":"Comma-separated fan UUIDs to fetch insights for (max 20)"},"required":true,"description":"Comma-separated fan UUIDs to fetch insights for (max 20)","name":"fanUuids","in":"query"}],"responses":{"200":{"description":"Insight data about the user's fans","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"type":"object","nullable":true,"properties":{"status":{"type":"string","enum":["subscriber","expired","follower","not_contactable"],"description":"Current fan status"},"spending":{"type":"object","properties":{"lastPurchaseAt":{"type":"string","nullable":true,"format":"date-time","description":"Date of last purchase (ISO 8601) or null if no purchases"},"total":{"type":"object","properties":{"gross":{"type":"number","description":"Total amount this fan paid across all transactions, in USD cents"}},"required":["gross"]},"maxSinglePayment":{"type":"object","properties":{"gross":{"type":"number","description":"Largest single payment this fan made, in USD cents"}},"required":["gross"]},"sources":{"type":"object","additionalProperties":{"type":"object","properties":{"gross":{"type":"number","description":"Total amount paid by the fan for this source type, in USD cents"}},"required":["gross"]},"description":"Breakdown of spending by source"}},"required":["lastPurchaseAt","total","maxSinglePayment","sources"]},"subscription":{"type":"object","properties":{"createdAt":{"type":"string","nullable":true,"format":"date-time","description":"Date subscription was created (ISO 8601) or null if no subscription"},"renewsAt":{"type":"string","nullable":true,"format":"date-time","description":"Date subscription renews (ISO 8601) or null if no active subscription"},"autoRenewalEnabled":{"type":"boolean","description":"Whether fan has active recurring subscription"}},"required":["createdAt","renewsAt","autoRenewalEnabled"]}},"required":["status","spending","subscription"]},"description":"Map fan UUID -> insights payload (null when unavailable)"},"errors":{"type":"array","items":{"type":"object","properties":{"fanUuid":{"type":"string","format":"uuid"},"code":{"type":"string","enum":["NOT_FOUND","INTERNAL"]},"message":{"type":"string"}},"required":["fanUuid","code","message"]},"description":"Per-fan errors for unresolved entries"}},"required":["results","errors"]},"example":{"results":{"11111111-1111-1111-1111-111111111111":{"status":"subscriber","spending":{"lastPurchaseAt":"2024-01-14T00:00:00.000Z","total":{"gross":27700},"maxSinglePayment":{"gross":5000},"sources":{"message":{"gross":15000},"post":{"gross":8500},"referral":{"gross":4200}}},"subscription":{"createdAt":"2024-01-01T12:00:00.000Z","renewsAt":"2024-02-01T00:00:00.000Z","autoRenewalEnabled":true}},"22222222-2222-2222-2222-222222222222":null},"errors":[{"fanUuid":"22222222-2222-2222-2222-222222222222","code":"NOT_FOUND","message":"The specified fan does not exist or is not connected to this creator."}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/insights/fans/{userUuid}":{"get":{"summary":"Get fan insights","description":"Returns detailed insights about a specific fan for the authenticated creator, including spending statistics, subscription status, and fan engagement metrics.\n\n<Info>Scopes required: `read:insights`, `read:fan`</Info>","operationId":"getFanInsights","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Fan's UUID"},"required":true,"description":"Fan's UUID","name":"userUuid","in":"path"}],"responses":{"200":{"description":"Fan insights data","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["subscriber","expired","follower","not_contactable"],"description":"Current fan status"},"spending":{"type":"object","properties":{"lastPurchaseAt":{"type":"string","nullable":true,"format":"date-time","description":"Date of last purchase (ISO 8601) or null if no purchases"},"total":{"type":"object","properties":{"gross":{"type":"number","description":"Total amount this fan paid across all transactions, in USD cents"}},"required":["gross"]},"maxSinglePayment":{"type":"object","properties":{"gross":{"type":"number","description":"Largest single payment this fan made, in USD cents"}},"required":["gross"]},"sources":{"type":"object","additionalProperties":{"type":"object","properties":{"gross":{"type":"number","description":"Total amount paid by the fan for this source type, in USD cents"}},"required":["gross"]},"description":"Breakdown of spending by source"}},"required":["lastPurchaseAt","total","maxSinglePayment","sources"]},"subscription":{"type":"object","properties":{"createdAt":{"type":"string","nullable":true,"format":"date-time","description":"Date subscription was created (ISO 8601) or null if no subscription"},"renewsAt":{"type":"string","nullable":true,"format":"date-time","description":"Date subscription renews (ISO 8601) or null if no active subscription"},"autoRenewalEnabled":{"type":"boolean","description":"Whether fan has active recurring subscription"}},"required":["createdAt","renewsAt","autoRenewalEnabled"]}},"required":["status","spending","subscription"]},"example":{"status":"subscriber","spending":{"lastPurchaseAt":"2024-01-14T00:00:00.000Z","total":{"gross":27700},"maxSinglePayment":{"gross":5000},"sources":{"message":{"gross":15000},"post":{"gross":8500},"referral":{"gross":4200}}},"subscription":{"createdAt":"2024-01-01T12:00:00.000Z","renewsAt":"2024-02-01T00:00:00.000Z","autoRenewalEnabled":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media/uploads":{"post":{"summary":"Create multipart upload session","description":"Create a media record and start an S3 multipart upload session.\n\n    <Info>Scope required: `write:media`</Info>","operationId":"createUploadSession","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"filename":{"type":"string","minLength":1,"maxLength":255},"mediaType":{"type":"string","enum":["image","video","audio","document"]}},"required":["name","filename","mediaType"]}}}},"responses":{"200":{"description":"Upload session created","content":{"application/json":{"schema":{"type":"object","properties":{"mediaUuid":{"type":"string","format":"uuid"},"uploadId":{"type":"string"}},"required":["mediaUuid","uploadId"]},"example":{"mediaUuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","uploadId":"abc123XYZ789multipart"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media/uploads/{uploadId}/parts/{partNumber}/url":{"get":{"summary":"Get signed URL for upload part","description":"Return a presigned URL to upload a specific part number for a media upload session.\n\n    <Info>Scope required: `write:media`</Info>","operationId":"getUploadPartUrl","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string"},"required":true,"name":"uploadId","in":"path"},{"schema":{"type":"number","nullable":true},"required":false,"name":"partNumber","in":"path"}],"responses":{"200":{"description":"Signed URL for part upload","content":{"text/plain":{"schema":{"type":"string","format":"uri"},"example":"https://s3.amazonaws.com/fanvue-uploads/media/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a?partNumber=1&uploadId=abc123XYZ789multipart&X-Amz-Signature=..."}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media/uploads/{uploadId}":{"patch":{"summary":"Complete upload session","description":"Complete multipart upload in S3 and set media status to processing.\n    Media URLs will be available once processing completes.\n\n    <Info>Scope required: `write:media`</Info>","operationId":"completeUploadSession","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string"},"required":true,"name":"uploadId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parts":{"type":"array","items":{"type":"object","properties":{"ETag":{"type":"string"},"PartNumber":{"type":"number"}},"required":["PartNumber"]}}}}}}},"responses":{"200":{"description":"Upload session completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["created","processing","ready","error"]}},"required":["status"]},"example":{"status":"processing"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media":{"get":{"summary":"Get user's media list","description":"Returns a paginated list of media items for the authenticated user.\n\n    For media with status other than FINALISED, only uuid and status are returned.\n    For FINALISED media, all details including variants are included.\n\n    <Info>Scope required: `read:media`</Info>","operationId":"getUserMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","enum":["image","video","audio","document"]},"required":false,"name":"mediaType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"folderName","in":"query"},{"schema":{"type":"string","enum":["subscribers","followers","ppv","mass_messages"]},"required":false,"name":"usage","in":"query"},{"schema":{"type":"string","format":"uuid","description":"UUID of the user to check media purchases against. When provided, each media item will include a purchasedByFan boolean indicating if that user has purchased it."},"required":false,"description":"UUID of the user to check media purchases against. When provided, each media item will include a purchasedByFan boolean indicating if that user has purchased it.","name":"purchasedBy","in":"query"},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MediaStatus"},"description":"Comma-separated list of media status values"},"required":false,"name":"status","in":"query","style":"form","explode":false},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MediaVariantType"},"description":"Comma-separated list of media variant types"},"required":false,"name":"variants","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"List of user media","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]}},"required":["uuid","status"]},{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]},"createdAt":{"type":"string","nullable":true,"format":"date"},"url":{"type":"string"},"caption":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":"number","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"variantType":{"type":"string","enum":["blurred","main","thumbnail","thumbnail_gallery"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"}},"required":["uuid","status","createdAt","caption","description","name","mediaType","recommendedPrice"]}]},"description":"Array of media items"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","status":"ready","createdAt":"2024-01-15T00:00:00.000Z","caption":"Check out my latest video!","description":"Behind the scenes of my photoshoot","name":"photoshoot-video.mp4","mediaType":"video","recommendedPrice":500,"variants":[{"uuid":"e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b","variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.mp4","width":1920,"height":1080,"lengthMs":45000},{"uuid":"f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c","variantType":"thumbnail","displayPosition":1,"url":"https://media.fanvue.com/thumb/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":320,"height":180,"lengthMs":null},{"uuid":"a7b8c9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d","variantType":"blurred","displayPosition":2,"url":"https://media.fanvue.com/blur/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.mp4","width":1920,"height":1080,"lengthMs":45000}]},{"uuid":"b8c9d0e1-2f3a-4b5c-6d7e-8f9a0b1c2d3e","status":"processing"}],"pagination":{"page":1,"size":2,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media/bulk":{"get":{"summary":"Get bulk media by UUIDs","description":"Returns multiple media items in a single request.\n\n<Info>Scope required: `read:media`</Info>\n\n<Note>Maximum 20 media UUIDs per request.</Note>","operationId":"getBulkMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string"},"required":true,"name":"mediaUuids","in":"query"},{"schema":{"type":"string"},"required":false,"name":"variants","in":"query"}],"responses":{"200":{"description":"Bulk media response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]}},"required":["uuid","status"]},{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]},"createdAt":{"type":"string","nullable":true,"format":"date"},"url":{"type":"string"},"caption":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":"number","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"variantType":{"type":"string","enum":["blurred","main","thumbnail","thumbnail_gallery"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"}},"required":["uuid","status","createdAt","caption","description","name","mediaType","recommendedPrice"]},{"nullable":true}]},"description":"Map media UUID -> media payload (null when unavailable)"},"errors":{"type":"array","items":{"type":"object","properties":{"mediaUuid":{"type":"string","format":"uuid"},"code":{"type":"string","enum":["NOT_FOUND","INTERNAL"]},"message":{"type":"string"}},"required":["mediaUuid","code","message"]},"description":"Per-media errors for unresolved entries"}},"required":["results","errors"]},"example":{"results":{"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a":{"uuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","status":"ready","createdAt":"2024-01-15T00:00:00.000Z","caption":"Sunset at the beach","description":null,"name":"beach-sunset.jpg","mediaType":"image","recommendedPrice":null,"variants":[{"uuid":"c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f","variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":3840,"height":2160,"lengthMs":null},{"uuid":"d0e1f2a3-4b5c-6d7e-8f9a-0b1c2d3e4f5a","variantType":"thumbnail","displayPosition":1,"url":"https://media.fanvue.com/thumb/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":320,"height":180,"lengthMs":null},{"uuid":"e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b","variantType":"thumbnail_gallery","displayPosition":2,"url":"https://media.fanvue.com/gallery/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":400,"height":300,"lengthMs":null},{"uuid":"f2a3b4c5-6d7e-8f9a-0b1c-2d3e4f5a6b7c","variantType":"blurred","displayPosition":3,"url":"https://media.fanvue.com/blur/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":3840,"height":2160,"lengthMs":null}]},"00000000-0000-0000-0000-000000000000":null},"errors":[{"mediaUuid":"00000000-0000-0000-0000-000000000000","code":"NOT_FOUND","message":"Media not found"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media/{uuid}":{"get":{"summary":"Get media by UUID","description":"Returns a specific media item by its UUID for the authenticated user.\n\n    For media with status other than FINALISED, only uuid and status are returned.\n    For FINALISED media, all details including variants are included.\n\n    <Warning>Media URLs are only available through variants.\n    Specify the `variants` query parameter (e.g., `?variants=main,thumbnail,blurred`)\n    to include them in the response. Without this parameter, the `variants` field\n    will be an empty array and no media URLs will be returned.</Warning>\n\n    <Info>Scope required: `read:media`</Info>","operationId":"getUserMediaByUuid","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the user to check media purchase against. When provided, the media item will include a purchasedByFan boolean indicating if that user has purchased it."},"required":false,"description":"UUID of the user to check media purchase against. When provided, the media item will include a purchasedByFan boolean indicating if that user has purchased it.","name":"purchasedBy","in":"query"},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MediaVariantType"},"description":"Comma-separated list of media variant types"},"required":false,"name":"variants","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"Media item","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]}},"required":["uuid","status"]},{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]},"createdAt":{"type":"string","nullable":true,"format":"date"},"url":{"type":"string"},"caption":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":"number","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"variantType":{"type":"string","enum":["blurred","main","thumbnail","thumbnail_gallery"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"}},"required":["uuid","status","createdAt","caption","description","name","mediaType","recommendedPrice"]}]},"example":{"uuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","status":"ready","createdAt":"2024-01-15T00:00:00.000Z","caption":"Sunset at the beach","description":null,"name":"beach-sunset.jpg","mediaType":"image","recommendedPrice":null,"variants":[{"uuid":"c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f","variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":3840,"height":2160,"lengthMs":null},{"uuid":"d0e1f2a3-4b5c-6d7e-8f9a-0b1c2d3e4f5a","variantType":"thumbnail","displayPosition":1,"url":"https://media.fanvue.com/thumb/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":320,"height":180,"lengthMs":null},{"uuid":"e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b","variantType":"thumbnail_gallery","displayPosition":2,"url":"https://media.fanvue.com/gallery/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":400,"height":300,"lengthMs":null},{"uuid":"f2a3b4c5-6d7e-8f9a-0b1c-2d3e4f5a6b7c","variantType":"blurred","displayPosition":3,"url":"https://media.fanvue.com/blur/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":3840,"height":2160,"lengthMs":null}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media/{uuid}/grant":{"post":{"summary":"Grant a consumer access to a media item","description":"Grant a specific consumer access to a piece of media owned by the authenticated creator.\n    The grant is idempotent: repeated calls with the same parameters return the existing entitlement.\n\n    <Info>Scope required: `write:media`</Info>","operationId":"grantMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"consumerId":{"type":"string","format":"uuid","description":"UUID of the consumer to grant media access to"},"source":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","description":"Identifier for the granting application or reason (e.g. spin_the_wheel_reward)","example":"spin_the_wheel_reward"},"sourceRef":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier within the source, used for idempotency (e.g. spin attempt UUID)","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"required":["consumerId","source","sourceRef"]}}}},"responses":{"200":{"description":"Media access granted (or already existed)","content":{"application/json":{"schema":{"type":"object","properties":{"entitlementId":{"type":"string","format":"uuid","description":"UUID of the created or existing entitlement"},"status":{"type":"string","enum":["granted"]}},"required":["entitlementId","status"]},"example":{"entitlementId":"f1e2d3c4-b5a6-9870-fedc-ba0987654321","status":"granted"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media/{uuid}/entitled":{"get":{"summary":"Get media for an entitled consumer","description":"Returns a media item with signed variant URLs, but only if the specified consumer\n    has been granted access via a prior grant call.\n\n    <Warning>Media URLs are only available through variants.\n    Specify the `variants` query parameter (e.g., `?variants=main,thumbnail`)\n    to include them in the response.</Warning>\n\n    <Info>Scope required: `read:media`</Info>","operationId":"getEntitledMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the consumer whose entitlement to verify"},"required":true,"description":"UUID of the consumer whose entitlement to verify","name":"consumerId","in":"query"},{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MediaVariantType"},"description":"Comma-separated list of media variant types"},"required":false,"name":"variants","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"Media item with signed variant URLs","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]}},"required":["uuid","status"]},{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","processing","ready","error"]},"createdAt":{"type":"string","nullable":true,"format":"date"},"url":{"type":"string"},"caption":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":"number","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"variantType":{"type":"string","enum":["blurred","main","thumbnail","thumbnail_gallery"]},"displayPosition":{"type":"number"},"url":{"type":"string"},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"lengthMs":{"type":"number","nullable":true}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"}},"required":["uuid","status","createdAt","caption","description","name","mediaType","recommendedPrice"]}]},"example":{"uuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","status":"ready","createdAt":"2024-01-15T00:00:00.000Z","caption":"Sunset at the beach","description":null,"name":"beach-sunset.jpg","mediaType":"image","recommendedPrice":null,"variants":[{"uuid":"c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f","variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":3840,"height":2160,"lengthMs":null},{"uuid":"d0e1f2a3-4b5c-6d7e-8f9a-0b1c2d3e4f5a","variantType":"thumbnail","displayPosition":1,"url":"https://media.fanvue.com/thumb/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":320,"height":180,"lengthMs":null},{"uuid":"e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b","variantType":"thumbnail_gallery","displayPosition":2,"url":"https://media.fanvue.com/gallery/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":400,"height":300,"lengthMs":null},{"uuid":"f2a3b4c5-6d7e-8f9a-0b1c-2d3e4f5a6b7c","variantType":"blurred","displayPosition":3,"url":"https://media.fanvue.com/blur/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg","width":3840,"height":2160,"lengthMs":null}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/media/links/{uuid}/purchased":{"get":{"summary":"Check if the authenticated user has purchased a media link","description":"Returns whether the authenticated user has a paid invoice for the given media link.\n\n    Returns 404 if no media link with the given UUID exists.\n\n    <Info>Scope required: `read:media`</Info>","operationId":"getMediaLinkPurchaseStatus","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"}],"responses":{"200":{"description":"Purchase status for the media link","content":{"application/json":{"schema":{"type":"object","properties":{"purchased":{"type":"boolean","description":"Whether the authenticated user has paid for this media link"}},"required":["purchased"]},"example":{"purchased":true}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/posts":{"post":{"summary":"Create a new post","description":"Create a new post with optional media, text, and pricing.\n\n    <Info>Scope required: `write:post`</Info>","operationId":"createPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":5000,"description":"Text content of the post"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs to attach to the post"},"mediaPreviewUuid":{"type":"string","format":"uuid","description":"UUID of free preview media shown before unlock"},"price":{"type":"number","minimum":300,"description":"Price in cents for paid posts (requires media)"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","format":"date-time","description":"Future date/time to publish the post (ISO 8601 format)"},"expiresAt":{"type":"string","format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"collectionUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of content collection UUIDs to assign to the post"}},"required":["audience"]}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the created post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Check out my latest content!","price":999,"mediaPreviewUuid":"f1e2d3c4-b5a6-4789-8123-456789abcdef","audience":"subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":"2025-01-01T12:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/ValidationErrorResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"get":{"summary":"Get list of posts","description":"Returns a paginated list of posts created by the authenticated user. Posts are ordered by pinned status first, then by publication date (newest first).\n\n    <Info>Scope required: `read:post`</Info>","operationId":"getPosts","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to include unpublished posts (drafts and scheduled posts) in the results. Defaults to true."},"required":false,"description":"Whether to include unpublished posts (drafts and scheduled posts) in the results. Defaults to true.","name":"includeUnpublished","in":"query"}],"responses":{"200":{"description":"List of posts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"description":"Array of posts"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Check out my latest content!","price":null,"audience":"subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":true,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[{"uuid":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","label":"Behind the Scenes"}]},{"uuid":"223e4567-e89b-12d3-a456-426614174001","createdAt":"2024-12-31T18:00:00.000Z","text":"Happy New Year everyone!","price":500,"audience":"followers-and-subscribers","publishAt":null,"publishedAt":"2024-12-31T18:00:00.000Z","expiresAt":null,"mediaUuids":["b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7","c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8"],"mediaPreviewUuid":"f1e2d3c4-b5a6-4789-8123-456789abcdef","isPinned":false,"likesCount":103,"commentsCount":27,"tips":{"count":0,"totalGross":0,"totalNet":0},"collections":[]}],"pagination":{"page":1,"size":20,"hasMore":false}}}}},"400":{"$ref":"#/components/responses/ValidationErrorResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/posts/{uuid}":{"get":{"summary":"Get post by UUID","description":"Returns a specific post owned by the authenticated user by its UUID.\n\n    <Info>Scope required: `read:post`</Info>","operationId":"getPostByUuid","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to retrieve"},"required":true,"description":"UUID of the post to retrieve","name":"uuid","in":"path"}],"responses":{"200":{"description":"Post details","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Check out my latest content!","price":999,"audience":"subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":"f1e2d3c4-b5a6-4789-8123-456789abcdef","isPinned":true,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[{"uuid":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","label":"Behind the Scenes"},{"uuid":"e2f3a4b5-c6d7-8901-bcde-f12345678901","label":"Exclusive Content"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"patch":{"summary":"Update a post","description":"Update an existing post's properties. Only the post owner can edit their posts. All fields are optional — only provided fields will be updated.\n\n    If a scheduled post has its `publishAt` set to `null`, it will be published immediately.\n\n    <Info>Scope required: `write:post`</Info>","operationId":"updatePost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to update"},"required":true,"description":"UUID of the post to update","name":"uuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","nullable":true,"maxLength":5000,"description":"Text content of the post. Set to null to remove text."},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs to attach to the post (replaces existing media)"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media shown before unlock. Set to null to remove."},"price":{"type":"number","nullable":true,"minimum":300,"description":"Price in cents for paid posts. Set to null to make the post free."},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time to publish the post (ISO 8601 format). Set to null to publish immediately if currently scheduled."},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format). Set to null to remove expiration."},"collectionUuids":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Array of content collection UUIDs to assign to the post (replaces existing collections). Set to null to remove all collections."}}}}}},"responses":{"200":{"description":"Post updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Updated post content!","price":null,"audience":"followers-and-subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":true,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[{"uuid":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","label":"Behind the Scenes"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"delete":{"summary":"Delete a post","description":"Soft-delete an existing post. Only the post owner can delete their own post.\n\n    <Info>Scope required: `write:post`</Info>","operationId":"deletePost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to delete"},"required":true,"description":"UUID of the post to delete","name":"uuid","in":"path"}],"responses":{"204":{"description":"Post deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/posts/{uuid}/tips":{"get":{"summary":"Get tips for a post","description":"Returns a paginated list of tips received on a specific post. Only the post owner can view tips.\n\n    <Info>Scope required: `read:post`</Info>","operationId":"getPostTips","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to retrieve tips for"},"required":true,"description":"UUID of the post to retrieve tips for","name":"uuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of tips received on this post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"],"description":"User who sent the tip (null if user was deleted)"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"Date/time when the tip was paid"},"gross":{"type":"number","description":"Gross amount of the tip in cents"},"net":{"type":"number","description":"Net amount of the tip in cents (after platform fees)"}},"required":["user","createdAt","gross","net"]},"description":"Array of tips received on this post"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"createdAt":"2024-01-15T10:30:00.000Z","gross":500,"net":425},{"user":null,"createdAt":"2024-01-14T18:45:00.000Z","gross":200,"net":170}],"pagination":{"page":1,"size":2,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/posts/{uuid}/likes":{"get":{"summary":"Get likes for a post","description":"Returns a paginated list of likes received on a specific post.\n\n    <Info>Scope required: `read:post`</Info>","operationId":"getPostLikes","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to retrieve likes for"},"required":true,"description":"UUID of the post to retrieve likes for","name":"uuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of likes on this post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"],"description":"User who liked the post (null if user was deleted)"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the like was created (ISO 8601 format)"}},"required":["user","createdAt"]},"description":"Array of likes on this post"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"user":{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"createdAt":"2024-01-15T10:30:00.000Z"},{"user":{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z"},"createdAt":"2024-01-14T18:45:00.000Z"},{"user":null,"createdAt":"2024-01-13T12:00:00.000Z"}],"pagination":{"page":1,"size":2,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/posts/{uuid}/comments":{"get":{"summary":"Get comments for a post","description":"Returns a paginated list of comments on a specific post. Only the post owner can view comments.\n\n    <Info>Scope required: `read:post`</Info>","operationId":"getPostComments","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to retrieve comments for"},"required":true,"description":"UUID of the post to retrieve comments for","name":"uuid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of comments on this post","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the comment"},"text":{"type":"string","description":"Comment text content"},"user":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"}},"required":["uuid","handle","displayName","nickname","isTopSpender"],"description":"User who created the comment (null if user was deleted)"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the comment was created (ISO 8601 format)"},"updatedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the comment was last updated (ISO 8601 format)"}},"required":["uuid","text","user","createdAt","updatedAt"]},"description":"Array of comments on this post"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"550e8400-e29b-41d4-a716-446655440001","text":"Great content! Thanks for sharing!","user":{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","handle":"sarah","displayName":"Sarah Johnson","nickname":null,"isTopSpender":true},"createdAt":"2024-01-15T10:30:00.000Z","updatedAt":"2024-01-15T10:30:00.000Z"},{"uuid":"550e8400-e29b-41d4-a716-446655440002","text":"Love this post!","user":{"uuid":"b2c3d4e5-f678-90ab-cdef-123456789012","handle":"mike","displayName":"Mike Smith","nickname":null,"isTopSpender":false},"createdAt":"2024-01-15T09:15:00.000Z","updatedAt":"2024-01-15T09:15:00.000Z"},{"uuid":"550e8400-e29b-41d4-a716-446655440003","text":"[Comment from deleted user]","user":null,"createdAt":"2024-01-14T18:00:00.000Z","updatedAt":"2024-01-14T18:00:00.000Z"}],"pagination":{"page":1,"size":2,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"post":{"summary":"Create a comment on a post","description":"Create a new comment on a specific post. Only the post owner can create comments via this endpoint.\n\n    <Info>Scope required: `write:post`</Info>","operationId":"createPostComment","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to comment on"},"required":true,"description":"UUID of the post to comment on","name":"uuid","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":600,"description":"Comment text content (1–600 characters)"}},"required":["text"]}}}},"responses":{"201":{"description":"Comment created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the created comment"},"text":{"type":"string","description":"Comment text content"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the comment was created (ISO 8601 format)"},"updatedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the comment was last updated (ISO 8601 format)"}},"required":["uuid","text","createdAt","updatedAt"]},"example":{"uuid":"550e8400-e29b-41d4-a716-446655440001","text":"Thanks for the kind words!","createdAt":"2025-01-15T10:30:00.000Z","updatedAt":null}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/posts/{uuid}/repost":{"post":{"summary":"Repost content","description":"Re-surface an existing post by updating its publication date to now. This moves the post back to the top of the feed. Only the post owner can repost their own content.\n\n    <Info>Scope required: `write:post`</Info>","operationId":"repostPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to repost"},"required":true,"description":"UUID of the post to repost","name":"uuid","in":"path"}],"responses":{"200":{"description":"Post reposted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Check out my latest content!","price":null,"audience":"subscribers","publishAt":null,"publishedAt":"2025-03-15T14:30:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":false,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/posts/{uuid}/pin":{"post":{"summary":"Pin a post","description":"Pin a post so it appears at the top of the feed. Only the post owner can pin their own content.\n\n    <Info>Scope required: `write:post`</Info>","operationId":"pinPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to pin"},"required":true,"description":"UUID of the post to pin","name":"uuid","in":"path"}],"responses":{"200":{"description":"Post pinned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Updated post content!","price":null,"audience":"followers-and-subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":true,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[{"uuid":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","label":"Behind the Scenes"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"delete":{"summary":"Unpin a post","description":"Unpin a post so it returns to normal feed ordering. Only the post owner can unpin their own content.\n\n    <Info>Scope required: `write:post`</Info>","operationId":"unpinPost","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post to unpin"},"required":true,"description":"UUID of the post to unpin","name":"uuid","in":"path"}],"responses":{"200":{"description":"Post unpinned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the post"},"createdAt":{"type":"string","format":"date-time","description":"Date/time when the post was created (ISO 8601 format)"},"text":{"type":"string","nullable":true,"description":"Text content of the post"},"price":{"type":"number","nullable":true,"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":"string","nullable":true,"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":"string","nullable":true,"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs attached to the post"},"isPinned":{"type":"boolean","description":"Whether the post is pinned to the top of the feed"},"likesCount":{"type":"number","description":"Number of likes the post has received"},"commentsCount":{"type":"number","description":"Number of comments on the post"},"tips":{"type":"object","properties":{"count":{"type":"number","description":"Number of paid tips received on this post"},"totalGross":{"type":"number","description":"Total gross amount of paid tips in cents"},"totalNet":{"type":"number","description":"Total net amount of paid tips in cents (after platform fees)"}},"required":["count","totalGross","totalNet"],"description":"Tips statistics for this post"},"collections":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display name of the collection"}},"required":["uuid","label"]},"description":"Content collections this post belongs to"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt","mediaUuids","isPinned","likesCount","commentsCount","tips","collections"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","createdAt":"2025-01-01T12:00:00.000Z","text":"Updated post content!","price":null,"audience":"followers-and-subscribers","publishAt":null,"publishedAt":"2025-01-01T12:00:00.000Z","expiresAt":null,"mediaUuids":["a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"],"mediaPreviewUuid":null,"isPinned":true,"likesCount":42,"commentsCount":15,"tips":{"count":8,"totalGross":5000,"totalNet":4250},"collections":[{"uuid":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","label":"Behind the Scenes"}]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/posts/{uuid}/comments/{commentUuid}":{"delete":{"summary":"Delete a comment from a post","description":"Delete a comment from a post. The comment can be deleted by either the comment author or the post owner.\n\n    <Info>Scope required: `write:post`</Info>","operationId":"deletePostComment","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the post"},"required":true,"description":"UUID of the post","name":"uuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the comment to delete"},"required":true,"description":"UUID of the comment to delete","name":"commentUuid","in":"path"}],"responses":{"204":{"description":"Comment deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/subscribers":{"get":{"summary":"Get subscribers","description":"Returns a paginated list of users who have subscriptions to the authenticated user.\n\n    <Info>Scope required: `read:fan`</Info>","operationId":"listSubscribers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","enum":["name","subscribedAt"],"description":"Public field to sort by"},"required":false,"description":"Public field to sort by","name":"sortField","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction"},"required":false,"description":"Sort direction","name":"sortDirection","in":"query"}],"responses":{"200":{"description":"List of subscribers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"description":"Array of subscribers"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","nickname":"SarahK","displayName":"Sarah Jones","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"},{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","nickname":null,"displayName":"Mike Smithly","isTopSpender":false,"avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","registeredAt":"2024-01-10T12:00:00.000Z","role":"creator"}],"pagination":{"page":1,"size":2,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/tracking-links":{"get":{"summary":"List tracking links","description":"List authenticated user's tracking links with cursor-based pagination.\n\n<Info>Scope required: `read:tracking_links`</Info>","operationId":"listTrackingLinks","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of results to return (default 20)"},"required":false,"description":"Number of results to return (default 20)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"description":"Cursor for pagination","name":"cursor","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter links created on or after this ISO datetime"},"required":false,"description":"Filter links created on or after this ISO datetime","name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter links created before this ISO datetime"},"required":false,"description":"Filter links created before this ISO datetime","name":"createdBefore","in":"query"}],"responses":{"200":{"description":"List of tracking links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Tracking link UUID"},"name":{"type":"string","description":"Name of the tracking link"},"linkUrl":{"type":"string","description":"Tracking link URL (e.g., 'fv-123')"},"externalSocialPlatform":{"type":"string","enum":["facebook","instagram","other","reddit","snapchat","tiktok","twitter","youtube"],"description":"Social platform"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"},"clicks":{"type":"number","description":"Number of clicks on this link"},"engagement":{"type":"object","properties":{"acquiredSubscribers":{"type":"number","description":"Number of subscribers acquired through this link (first-click attribution - users only counted for the first link they clicked)"},"acquiredFollowers":{"type":"number","description":"Number of followers acquired through this link (first-click attribution - users only counted for the first link they clicked)"},"totalSubscribers":{"type":"number","description":"Total count of all users who clicked this link and are currently active subscribers"},"totalFollowers":{"type":"number","description":"Total count of all users who clicked this link and are currently followers"}},"required":["acquiredSubscribers","acquiredFollowers","totalSubscribers","totalFollowers"],"description":"Engagement metrics from this tracking link"},"earnings":{"type":"object","nullable":true,"properties":{"totalGross":{"type":"number","description":"Total gross earnings from this link (before fees)"},"totalNet":{"type":"number","description":"Total net earnings from this link (after fees)"}},"required":["totalGross","totalNet"],"description":"Earnings from this tracking link (null for newly created links)"}},"required":["uuid","name","linkUrl","externalSocialPlatform","createdAt","clicks","engagement","earnings"]}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page"}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"d4e5f6g7-8h9i-0j1k-2l3m-n4o5p6q7r8s9","name":"TikTok Profile","linkUrl":"fv-123456","externalSocialPlatform":"tiktok","createdAt":"2024-01-15T00:00:00.000Z","clicks":342,"engagement":{"acquiredSubscribers":28,"acquiredFollowers":15,"totalSubscribers":35,"totalFollowers":20},"earnings":{"totalGross":150000,"totalNet":120000}},{"uuid":"e5f6g7h8-9i0j-1k2l-3m4n-o5p6q7r8s9t0","name":"Instagram Bio","linkUrl":"fv-789012","externalSocialPlatform":"instagram","createdAt":"2024-01-14T00:00:00.000Z","clicks":156,"engagement":{"acquiredSubscribers":12,"acquiredFollowers":8,"totalSubscribers":18,"totalFollowers":12},"earnings":{"totalGross":75000,"totalNet":60000}}],"nextCursor":"eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE0VDAwOjAwOjAwLjAwMFoifQ=="}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"post":{"summary":"Create a tracking link","description":"Create a new tracking link for the authenticated user.\n\n<Info>Scope required: `write:tracking_links`</Info>","operationId":"createTrackingLink","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the tracking link"},"externalSocialPlatform":{"type":"string","enum":["facebook","instagram","other","reddit","snapchat","tiktok","twitter","youtube"],"description":"Social platform"}},"required":["name","externalSocialPlatform"]}}}},"responses":{"201":{"description":"Tracking link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Tracking link UUID"},"name":{"type":"string","description":"Name of the tracking link"},"linkUrl":{"type":"string","description":"Tracking link URL (e.g., 'fv-123')"},"externalSocialPlatform":{"type":"string","enum":["facebook","instagram","other","reddit","snapchat","tiktok","twitter","youtube"],"description":"Social platform"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"},"clicks":{"type":"number","description":"Number of clicks on this link"},"engagement":{"type":"object","properties":{"acquiredSubscribers":{"type":"number","description":"Number of subscribers acquired through this link (first-click attribution - users only counted for the first link they clicked)"},"acquiredFollowers":{"type":"number","description":"Number of followers acquired through this link (first-click attribution - users only counted for the first link they clicked)"},"totalSubscribers":{"type":"number","description":"Total count of all users who clicked this link and are currently active subscribers"},"totalFollowers":{"type":"number","description":"Total count of all users who clicked this link and are currently followers"}},"required":["acquiredSubscribers","acquiredFollowers","totalSubscribers","totalFollowers"],"description":"Engagement metrics from this tracking link"},"earnings":{"type":"object","nullable":true,"properties":{"totalGross":{"type":"number","description":"Total gross earnings from this link (before fees)"},"totalNet":{"type":"number","description":"Total net earnings from this link (after fees)"}},"required":["totalGross","totalNet"],"description":"Earnings from this tracking link (null for newly created links)"}},"required":["uuid","name","linkUrl","externalSocialPlatform","createdAt","clicks","engagement","earnings"]},"example":{"uuid":"d4e5f6g7-8h9i-0j1k-2l3m-n4o5p6q7r8s9","name":"TikTok Profile","linkUrl":"fv-123456","externalSocialPlatform":"tiktok","createdAt":"2024-01-15T00:00:00.000Z","clicks":0,"engagement":{"acquiredSubscribers":0,"acquiredFollowers":0,"totalSubscribers":0,"totalFollowers":0},"earnings":null}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/tracking-links/{uuid}":{"delete":{"summary":"Delete a tracking link","description":"Delete a tracking link for the authenticated user.\n\n<Info>Scope required: `write:tracking_links`</Info>","operationId":"deleteTrackingLink","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Tracking link UUID"},"required":true,"description":"Tracking link UUID","name":"uuid","in":"path"}],"responses":{"204":{"description":"Tracking link deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/tracking-links/{uuid}/users":{"get":{"summary":"List users for a tracking link","description":"List users associated with a tracking link owned by the authenticated user.\n\n<Info>Scope required: `read:tracking_links`</Info>","operationId":"listTrackingLinkUsers","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Tracking link UUID"},"required":true,"description":"Tracking link UUID","name":"uuid","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Number of results to return (default 20)"},"required":false,"description":"Number of results to return (default 20)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"description":"Cursor for pagination","name":"cursor","in":"query"}],"responses":{"200":{"description":"List of users associated with the tracking link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":"string","nullable":true},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":"string","nullable":true},"registeredAt":{"type":"string","format":"date-time"},"status":{"type":"string","nullable":true,"enum":["subscriber","follower","expired","deleted"],"description":"User's relationship status with the creator: subscriber (active subscription), follower (following only), expired (subscription ended), deleted (user soft-deleted), or null (registered via link but no current relationship)"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt","status"]},"description":"Users associated with this tracking link"},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page"}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"sarah-jones","displayName":"Sarah Jones","nickname":"SarahK","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/fan-a.jpg","registeredAt":"2024-01-15T00:00:00.000Z","status":"subscriber"},{"uuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","handle":"mike-smith","displayName":"Mike Smithly","nickname":null,"isTopSpender":false,"avatarUrl":null,"registeredAt":"2024-01-14T00:00:00.000Z","status":"follower"}],"nextCursor":"456"}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/tracking-links/{uuid}/users/{userUuid}/metadata":{"get":{"summary":"Get tracking metadata for a user","description":"Get the custom tracking metadata from a user's most recent impression on a tracking link.\n\n<Info>Scope required: `read:tracking_links`</Info>","operationId":"getUserTrackingMetadata","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Tracking link UUID"},"required":true,"description":"Tracking link UUID","name":"uuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"User UUID"},"required":true,"description":"User UUID","name":"userUuid","in":"path"}],"responses":{"200":{"description":"User's tracking metadata","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Custom metadata from the user's most recent impression on this link"}},"required":["metadata"]},"example":{"metadata":{"lead_id":"xyz123","source":"snapchat","conversation_id":"abc456"}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed OR invalid UUID","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/InvalidUuidError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/users/me":{"get":{"summary":"Get current user","description":"Get details of the currently authenticated user.\n\n    <Info>Scope required: `read:self`</Info>","operationId":"getCurrentUser","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"Current user details","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"handle":{"type":"string"},"bio":{"type":"string"},"displayName":{"type":"string"},"isCreator":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"},"avatarUrl":{"type":"string","nullable":true},"bannerUrl":{"type":"string","nullable":true},"likesCount":{"type":"number"},"fanCounts":{"type":"object","properties":{"followersCount":{"type":"number"},"subscribersCount":{"type":"number"}},"required":["followersCount","subscribersCount"]},"contentCounts":{"type":"object","properties":{"imageCount":{"type":"number"},"videoCount":{"type":"number"},"audioCount":{"type":"number"},"postCount":{"type":"number"},"payToViewPostCount":{"type":"number"}},"required":["imageCount","videoCount","audioCount","postCount","payToViewPostCount"]}},"required":["uuid","email","handle","bio","displayName","isCreator","createdAt","updatedAt","avatarUrl","bannerUrl"]},"example":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","email":"johnny@fanvue.com","handle":"johnny-doey","bio":"Content creator and influencer","displayName":"Johnny Doey","isCreator":true,"createdAt":"2023-01-15T10:30:00.000Z","updatedAt":"2024-12-01T14:20:00.000Z","avatarUrl":"https://media.fanvue.com/user-avatar.jpg","bannerUrl":"https://media.fanvue.com/user-banner.jpg","likesCount":1250,"fanCounts":{"followersCount":3420,"subscribersCount":890},"contentCounts":{"imageCount":145,"videoCount":67,"audioCount":12,"postCount":234,"payToViewPostCount":45}}}}},"400":{"$ref":"#/components/responses/UnsupportedVersionResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/vault/folders":{"post":{"summary":"Create a vault folder","description":"Create a new folder in the authenticated user's vault.\n\n<Info>Scope required: `write:media`</Info>","operationId":"createVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Name for the new folder"}},"required":["name"]}}}},"responses":{"201":{"description":"Folder created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Folder name"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the folder was created"},"mediaCount":{"type":"number","description":"Number of media items in the folder"}},"required":["name","createdAt","mediaCount"]},"example":{"name":"My Photos","createdAt":"2025-01-15T10:30:00.000Z","mediaCount":0}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"409":{"description":"Folder with this name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"get":{"summary":"List vault folders","description":"Returns a paginated list of folders in the authenticated user's vault.\n\n<Info>Scope required: `read:media`</Info>","operationId":"listVaultFolders","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"responses":{"200":{"description":"List of vault folders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Folder name"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the folder was created"},"mediaCount":{"type":"number","description":"Number of media items in the folder"}},"required":["name","createdAt","mediaCount"]},"description":"Array of vault folders"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"name":"My Photos","createdAt":"2025-01-15T10:30:00.000Z","mediaCount":42},{"name":"Videos","createdAt":"2025-01-16T14:20:00.000Z","mediaCount":15}],"pagination":{"page":1,"size":20,"hasMore":false}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/vault/folders/{folderName}":{"get":{"summary":"Get vault folder details","description":"Returns details of a specific folder by name.\n\n<Info>Scope required: `read:media`</Info>","operationId":"getVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"}],"responses":{"200":{"description":"Folder details","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Folder name"},"createdAt":{"type":"string","nullable":true,"format":"date","description":"When the folder was created"},"mediaCount":{"type":"number","description":"Number of media items in the folder"}},"required":["name","createdAt","mediaCount"]},"example":{"name":"My Photos","createdAt":"2025-01-15T10:30:00.000Z","mediaCount":42}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"patch":{"summary":"Rename vault folder","description":"Rename an existing folder in the authenticated user's vault.\n\n<Info>Scope required: `write:media`</Info>","operationId":"renameVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"New name for the folder"}},"required":["name"]}}}},"responses":{"204":{"description":"Folder renamed successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"409":{"description":"Folder with the new name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"delete":{"summary":"Delete vault folder","description":"Delete a folder from the authenticated user's vault.\nMedia items in the folder will be detached but not deleted.\n\n<Info>Scope required: `write:media`</Info>","operationId":"deleteVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"}],"responses":{"204":{"description":"Folder deleted successfully"},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/vault/folders/{folderName}/media":{"get":{"summary":"List media in folder","description":"Returns a paginated list of media items in the specified folder.\n\n<Info>Scope required: `read:media`</Info>","operationId":"listVaultFolderMedia","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"Page number to retrieve (starts from 1)"},"required":false,"description":"Page number to retrieve (starts from 1)","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15,"description":"Number of items to return per page (1-50, default: 15)"},"required":false,"description":"Number of items to return per page (1-50, default: 15)","name":"size","in":"query"}],"responses":{"200":{"description":"List of media in folder","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"createdAt":{"type":"string","nullable":true,"format":"date"},"mediaType":{"type":"string"}},"required":["uuid","name","createdAt","mediaType"]},"description":"Array of media items"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"size":{"type":"number","description":"Number of records returned in this response"},"hasMore":{"type":"boolean","description":"Whether there are more items available on subsequent pages"}},"required":["page","size","hasMore"],"description":"Pagination information"}},"required":["data","pagination"]},"example":{"data":[{"uuid":"550e8400-e29b-41d4-a716-446655440000","name":"photo1.jpg","createdAt":"2025-01-15T10:30:00.000Z","mediaType":"image"},{"uuid":"550e8400-e29b-41d4-a716-446655440001","name":"video1.mp4","createdAt":"2025-01-16T14:20:00.000Z","mediaType":"video"}],"pagination":{"page":1,"size":20,"hasMore":true}}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}},"post":{"summary":"Add media to folder","description":"Add one or more media items to the specified folder.\nMedia items must belong to the authenticated user.\n\n<Info>Scope required: `write:media`</Info>","operationId":"attachMediaToVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"UUIDs of media items to attach to the folder"}},"required":["mediaUuids"]}}}},"responses":{"201":{"description":"Media added to folder","content":{"application/json":{"schema":{"type":"object","properties":{"addedCount":{"type":"number","description":"Number of media items successfully added"}},"required":["addedCount"]}}}},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/vault/folders/{folderName}/media/{mediaUuid}":{"delete":{"summary":"Remove media from folder","description":"Remove a media item from the specified folder.\nThe media item itself is not deleted, only the folder association.\n\n<Info>Scope required: `write:media`</Info>","operationId":"detachMediaFromVaultFolder","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Folder name (URL-encoded in path)"},"required":true,"description":"Folder name (URL-encoded in path)","name":"folderName","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"mediaUuid","in":"path"}],"responses":{"204":{"description":"Media removed from folder"},"400":{"description":"Bad Request - API version not supported OR validation failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnsupportedVersionError"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/UnauthorizedResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}}}}