{"openapi":"3.1.0","info":{"title":"Fanvue API","version":"0.1"},"components":{"securitySchemes":{"BearerAuth":{"type":"oauth2","description":"OAuth 2.0 access token, presented as a JWT bearer token in the `Authorization` header. Obtain a token via the authorization-code flow; the scopes granted to the token determine which operations it may call.","flows":{"authorizationCode":{"authorizationUrl":"https://auth.fanvue.com/oauth2/auth","tokenUrl":"https://auth.fanvue.com/oauth2/token","refreshUrl":"https://auth.fanvue.com/oauth2/token","scopes":{"read:self":"Access your own user profile information, including basic account details and settings.","read:chat":"Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.","write:chat":"Create new chats and send messages. This scope is required for any chat-related actions that modify data.","read:experience":"Exchange a fan's experience token for the resolved experience and the fan's identity, so an embedded fan-facing experience can render the right content.","write:experience":"Request that the creator publish or unpublish a fan-facing experience. The app mints a request token; the creator confirms and Fanvue performs the change.","read:fan":"Access fan-related data and information within the platform.","read:post":"Read posts, including post details, comments, likes, and tips.","write:post":"Create, edit, and manage posts and content on behalf of users.","read:media":"Access media files, images, videos, and other content assets.","write:media":"Upload, modify, and manage media files and content assets. Also required for vault folder management.","read:creator":"Access creator profiles, content, and creator-specific information.","write:creator":"Modify creator profiles, settings, and creator-specific data.","read:insights":"Access analytics, metrics, and insights data for performance tracking.","read:tracking_links":"Read tracking links and the users associated with them, including per-user tracking metadata.","write:tracking_links":"Create and delete tracking links.","read:agency":"Read agency information, including the agency's team members.","write:agency":"Manage agency team members and invites, including inviting new team members and creators."}}}}},"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.)"},"PerKeyError":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden","not_found","internal"]}},"required":["error"],"description":"Per-key error returned inside a batch endpoint's 200 response when an individual key cannot be resolved: forbidden (scope doesn't grant access to this key), not_found (key doesn't exist), or internal (server failure on this key only). Batches keep partial results instead of failing the whole request."},"EarningSource":{"type":"string","enum":["all","affiliate","appStore","checkoutLink","fanExperience","mediaLink","message","post","referral","renewal","subscription","tip","giveaway","refund","chargeback"],"description":"Earning source. Reversals are surfaced here too: `refund` and `chargeback` rows carry negative gross/net, matching /insights/spending."},"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":{"/account-health":{"get":{"summary":"Get account health","description":"Get the authenticated creator's account health summary: total warnings issued against the account and how many media items moderation has removed or is currently reviewing.\n\nThis is confidential moderation data and only ever reflects the authenticated creator's own account.","operationId":"getAccountHealth","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Account health summary","content":{"application/json":{"schema":{"type":"object","properties":{"totalWarnings":{"type":"integer","description":"Total number of warnings issued against the creator's account"},"totalRemovedMedia":{"type":"integer","description":"Total number of the creator's media items removed by moderation"},"totalInReviewMedia":{"type":"integer","description":"Total number of the creator's media items currently under moderation review"}},"required":["totalWarnings","totalRemovedMedia","totalInReviewMedia"]},"example":{"totalWarnings":2,"totalRemovedMedia":1,"totalInReviewMedia":3}}}},"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"}}}},"/account-health/flagged-media":{"get":{"summary":"List flagged media","description":"List the authenticated creator's media items flagged by moderation, most recent first: media removed by moderation and media currently under review. Use the `status` query parameter to narrow to one of the two.\n\nOnly moderation metadata is returned, never the media content itself. This is confidential moderation data and only ever reflects the authenticated creator's own media.","operationId":"listFlaggedMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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":["in_review","removed"],"description":"Filter to media with this moderation status. Returns both in_review and removed media when omitted."},"required":false,"description":"Filter to media with this moderation status. Returns both in_review and removed media when omitted.","name":"status","in":"query"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of flagged media","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Media UUID"},"mediaType":{"type":"string","enum":["image","video","audio","document","unknown"]},"moderationStatus":{"type":"string","enum":["in_review","removed"],"description":"Moderation status of the media: in_review (awaiting a moderation decision) or removed (taken down by moderation)"},"createdAt":{"type":"string","format":"date-time","description":"When the media was uploaded"}},"required":["uuid","mediaType","moderationStatus","createdAt"]},"description":"The creator's flagged media items, most recent first"},"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-4a7b-8c9d-0e1f2a3b4c5d","mediaType":"video","moderationStatus":"in_review","createdAt":"2024-02-12T18:45:00.000Z"},{"uuid":"b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e","mediaType":"image","moderationStatus":"removed","createdAt":"2024-01-20T11:15:00.000Z"}],"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"}}}},"/agencies/team-members":{"get":{"summary":"List team members","description":"Get a list of all team members in the authenticated user's agency.\n<Info>Requires: Agency admin access</Info>","operationId":"listTeamMembers","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:agency"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n</Info>"},"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","null"]},"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<Info>Requires: Agency admin access</Info>","operationId":"updateTeamMember","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"}],"security":[{"BearerAuth":["write:agency"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:agency` — Manage agency team members and invites, including inviting new team members and creators.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":["string","null"],"description":"Nickname for the team member"},"creatorUuids":{"type":["array","null"],"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","null"]},"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<Info>Requires: Agency admin access</Info>","operationId":"createAgencyInvite","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:agency"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:agency` — Manage agency team members and invites, including inviting new team members and creators.\n</Info>"},"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<Info>Requires: Agency admin access</Info>","operationId":"createCreatorInvite","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:agency"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:agency` — Manage agency team members and invites, including inviting new team members and creators.\n</Info>"},"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/posts":{"post":{"summary":"Bulk-create posts across creators","description":"Create (and optionally schedule) multiple posts across one or more creators in a single request.\n\nEach item reuses the same validation, scheduling (`publishAt`/`expiresAt`) and creation path as the single-creator `createCreatorPost` endpoint, and access is enforced per `creatorUserUuid` exactly as that endpoint does.\n\nThe request returns HTTP `200` whenever the envelope is valid. Each item is reported independently in `results` (index-aligned with the request `posts` array) as either a success or an error, so one creator's failure never sinks the whole batch.\n\n<Info>Requires: `write:post` and `write:creator` scopes, plus access to each creator (agency assignment/admin, or self).</Info>","operationId":"bulkCreateAgencyPosts","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"allOf":[{"type":"object","properties":{"creatorUserUuid":{"type":"string","format":"uuid","description":"UUID of the creator to create the post for"}},"required":["creatorUserUuid"]},{"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"]}]},"minItems":1,"maxItems":100,"description":"Array of posts to create across creators (1–100)"}},"required":["posts"]}}}},"responses":{"200":{"description":"Batch processed. Per-item success/failure is reported in `results`; a 200 does not imply every item succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"index":{"type":"integer","description":"Zero-based index of this item in the request `posts` array"},"creatorUserUuid":{"type":"string","format":"uuid","description":"Creator the post was created for"},"status":{"type":"string","enum":["success"],"description":"Indicates this item succeeded"},"data":{"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post expires (ISO 8601 format)"}},"required":["uuid","createdAt","text","price","mediaPreviewUuid","audience","publishAt","publishedAt","expiresAt"],"description":"The created post"}},"required":["index","creatorUserUuid","status","data"]},{"type":"object","properties":{"index":{"type":"integer","description":"Zero-based index of this item in the request `posts` array"},"creatorUserUuid":{"type":"string","format":"uuid","description":"Creator this item targeted"},"status":{"type":"string","enum":["error"],"description":"Indicates this item failed"},"code":{"anyOf":[{"type":"number","enum":[400]},{"type":"number","enum":[403]},{"type":"number","enum":[404]}],"description":"HTTP-style status for the failure: 403 (creator exists but caller lacks access), 404 (creator not found), 400 (validation failed)"},"message":{"type":"string","description":"Human-readable failure reason"}},"required":["index","creatorUserUuid","status","code","message"]}]},"description":"Per-item results, index-aligned with the request `posts` array"}},"required":["results"]},"example":{"results":[{"index":0,"creatorUserUuid":"123e4567-e89b-12d3-a456-426614174000","status":"success","data":{"uuid":"a1b2c3d4-e5f6-4789-8123-456789abcdef","createdAt":"2025-01-01T12:00:00.000Z","text":"Scheduled drop for tomorrow!","price":null,"mediaPreviewUuid":null,"audience":"subscribers","publishAt":"2025-01-02T09:00:00.000Z","publishedAt":null,"expiresAt":null}},{"index":1,"creatorUserUuid":"223e4567-e89b-12d3-a456-426614174001","status":"error","code":404,"message":"Creator not found or not assigned to team member"}]}}}},"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/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\nHistorical stats are precomputed daily and the current UTC day is included live at read time. Performance metrics (messages, PPV sends and unlocks, ratios, active hours, response time) are attributed to the day the content was sent. Revenue is attributed to the day of purchase, and earnings per active hour divides that purchase-date revenue by send-date active hours.\n<Info>Requires: Agency admin access</Info>","operationId":"getChatterLeaderboard","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"}],"security":[{"BearerAuth":["read:agency"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n</Info>"},"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","null"],"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","null"],"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/insights/overview":{"get":{"summary":"Get agency insights headline metrics","description":"Returns the headline metrics for the authenticated user's agency: total earnings, newly acquired fans, average revenue per paying fan, the 30-day retention snapshot and average fan lifetime, aggregated across every creator the agency manages.\n\nFigures come from the daily warehouse export, so they lag live platform data by up to a day. All money is USD cents; rates are fractions, not percentages.\n\n`totalEarnings` and `arpu` are not two views of one number and will not reconcile. `totalEarnings` is what the agency's creators earned, excluding refunds and chargebacks, and includes money with no fan behind it such as referrals. `arpu` measures what fans paid, so it drops those and subtracts reversals — the same definition the creator-level `/insights/top-spenders` uses. Expect `arpu.grossSpend` to be the smaller figure.\n\n`retention` and `averageFanLifetime` are snapshots computed on the warehouse's own windows — the 30-day cohort and all-time respectively — so `startDate`/`endDate` do not affect them.\n\nNo comparison period is returned: to show a change against the preceding period, request the same endpoint again for that range.\n<Info>Requires: Agency admin access</Info>","operationId":"getAgencyInsightsOverview","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Comma-separated list of creator UUIDs (max 50)"},"required":false,"description":"Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50). Every uuid must belong to the agency: one that does not fails the whole request with 403 rather than being ignored.","name":"creatorUuids","in":"query","style":"form","explode":false}],"security":[{"BearerAuth":["read:agency","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Agency insights headline metrics","content":{"application/json":{"schema":{"type":"object","properties":{"totalEarnings":{"type":"object","properties":{"gross":{"type":"integer","description":"Gross earnings across the agency's creators in the date range, excluding reversals. USD cents."},"net":{"type":"integer","description":"Creator-net earnings (after platform fees) across the agency's creators in the date range, excluding reversals. USD cents."},"currency":{"type":"string","enum":["USD"],"description":"Always 'USD'. Warehouse figures are reported in USD."}},"required":["gross","net","currency"],"description":"Total agency earnings over the requested date range. Everything the agency's creators earned, whether or not a fan was behind it, with refunds and chargebacks left out — so this does not equal `arpu.grossSpend`/`netSpend`."},"newFans":{"type":"integer","description":"Distinct fans first acquired by any of the agency's creators in the date range"},"arpu":{"type":"object","properties":{"grossArpu":{"type":"number","description":"Gross spend divided by paying fan count, in USD cents. Not rounded."},"netArpu":{"type":"number","description":"Net spend divided by paying fan count, in USD cents. Not rounded."},"grossSpend":{"type":"integer","description":"Total gross fan spend in the date range, net of refunds and chargebacks. USD cents."},"netSpend":{"type":"integer","description":"Total net fan spend in the date range, net of refunds and chargebacks. USD cents."},"fanCount":{"type":"integer","description":"Distinct fans who spent in the date range"},"currency":{"type":"string","enum":["USD"],"description":"Always 'USD'. Warehouse figures are reported in USD."}},"required":["grossArpu","netArpu","grossSpend","netSpend","fanCount","currency"],"description":"Average revenue per paying fan over the requested date range. These are fan-spend figures, not earnings: money with no fan behind it (referrals, affiliate) is excluded, and reversals are subtracted the same way the creator-level `/insights/top-spenders` does it. Both are therefore lower than `totalEarnings` and the two will not reconcile."},"retention":{"type":"object","properties":{"retentionRate":{"type":"number","description":"Retained fans divided by cohort fans, as a fraction (0.88 means 88%). 0 when the cohort is empty."},"cohortFanCount":{"type":"integer","description":"Paying fans in the cohort window"},"retainedFanCount":{"type":"integer","description":"Cohort fans who paid again in the reporting window"},"revenueRetentionRate":{"type":"number","description":"Retained gross revenue divided by cohort gross revenue, as a fraction. Can exceed 1 when retained fans spend more than the cohort did."},"cohortGrossRevenue":{"type":"integer","description":"Gross revenue from the cohort window. USD cents."},"retainedGrossRevenue":{"type":"integer","description":"Gross revenue retained in the reporting window. USD cents."}},"required":["retentionRate","cohortFanCount","retainedFanCount","revenueRetentionRate","cohortGrossRevenue","retainedGrossRevenue"],"description":"Fixed 30-day retention snapshot, cohort-weighted across the agency's creators. Computed by the data warehouse on its own cohort/reporting windows and therefore NOT affected by startDate/endDate."},"averageFanLifetime":{"type":"object","properties":{"activeAvgDays":{"type":"number","description":"Average lifetime in days of fans still active with one of the agency's creators"},"activeFanCount":{"type":"integer","description":"Fans counted in activeAvgDays"},"churnedAvgDays":{"type":"number","description":"Average lifetime in days of fans who have churned"},"churnedFanCount":{"type":"integer","description":"Fans counted in churnedAvgDays"}},"required":["activeAvgDays","activeFanCount","churnedAvgDays","churnedFanCount"],"description":"All-time average fan lifetime, split by active and churned fans. Only fans with two or more paid transactions are counted, and the figures are NOT affected by startDate/endDate."}},"required":["totalEarnings","newFans","arpu","retention","averageFanLifetime"]},"example":{"totalEarnings":{"gross":4820000,"net":4097000,"currency":"USD"},"newFans":412,"arpu":{"grossArpu":2881.25,"netArpu":2449.0625,"grossSpend":4610000,"netSpend":3918500,"fanCount":1600,"currency":"USD"},"retention":{"retentionRate":0.88,"cohortFanCount":900,"retainedFanCount":792,"revenueRetentionRate":1.05,"cohortGrossRevenue":2100000,"retainedGrossRevenue":2205000},"averageFanLifetime":{"activeAvgDays":72.2,"activeFanCount":310,"churnedAvgDays":41.5,"churnedFanCount":590}}}}},"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/insights/demographics":{"get":{"summary":"List agency fan spend by country (cursor-paginated)","description":"Returns the agency's paying fans grouped by billing country over the requested date range, ordered by fan count descending, then gross spend, then country code. Fans whose country is unknown are excluded, so shares should be computed against the returned rows rather than against the agency's total fan count.\n\nPage with the opaque `nextCursor` from the previous response. The result set is bounded by the requested date range, so `total` is not computed and is always `null`.\n<Info>Requires: Agency admin access</Info>","operationId":"getAgencyDemographics","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","description":"Opaque pagination cursor from a previous response's `nextCursor`. Omit to fetch the first page."},"required":false,"description":"Opaque pagination cursor from a previous response's `nextCursor`. Omit to fetch the first page.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":15,"description":"Number of items to return (1-50, default: 15)"},"required":false,"description":"Number of items to return (1-50, default: 15)","name":"size","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Comma-separated list of creator UUIDs (max 50)"},"required":false,"description":"Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50). Every uuid must belong to the agency: one that does not fails the whole request with 403 rather than being ignored.","name":"creatorUuids","in":"query","style":"form","explode":false}],"security":[{"BearerAuth":["read:agency","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Cursor-paginated fan-country distribution","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code of the fans' billing country"},"fanCount":{"type":"integer","description":"Distinct fans from this country who spent in the range"},"gross":{"type":"integer","description":"Gross spend from this country in the date range, net of refunds and chargebacks, so it can be negative. USD cents."},"net":{"type":"integer","description":"Net spend from this country in the date range, net of refunds and chargebacks, so it can be negative. USD cents."}},"required":["country","fanCount","gross","net"]},"description":"Array of fan-country rows, ordered by fan count descending"},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page, or null when there are no more results"},"total":{"type":["integer","null"],"description":"Total number of items across all pages, or null when no count is computed"}},"required":["data","nextCursor","total"]},"example":{"data":[{"country":"US","fanCount":842,"gross":2410000,"net":2048500},{"country":"GB","fanCount":311,"gross":890000,"net":756500},{"country":"DE","fanCount":146,"gross":412000,"net":350200}],"nextCursor":null,"total":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/insights/top-fans":{"get":{"summary":"Get the agency's five highest-spending fans","description":"Returns at most five rows: the fans who spent the most across the agency's creators over the requested date range, best first. Not paginated — ranking is done in the database by `earningsView` so that the five rows returned are the five highest by the figure you are showing.\n\nA fan can spend across several of the agency's creators, so `gross`/`net` are their combined spend and `topCreator` is the creator they spent the most on in the range, by the same earnings view. Amounts are USD cents from the daily warehouse export.\n<Info>Requires: Agency admin access</Info>","operationId":"getAgencyTopFans","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Comma-separated list of creator UUIDs (max 50)"},"required":false,"description":"Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50). Every uuid must belong to the agency: one that does not fails the whole request with 403 rather than being ignored.","name":"creatorUuids","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["net","gross"],"default":"gross","description":"Which earnings figure to rank by. Both figures are returned on every row regardless."},"required":false,"description":"Which earnings figure to rank by. Both figures are returned on every row regardless.","name":"earningsView","in":"query"}],"security":[{"BearerAuth":["read:agency","read:creator","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"responses":{"200":{"description":"The agency's five highest-spending fans","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID of the fan"},"handle":{"type":"string","description":"Fan's handle on the platform"},"displayName":{"type":"string","description":"Fan's display name"},"avatarUrl":{"type":["string","null"],"description":"URL of the fan's avatar image, or null"},"gross":{"type":"integer","description":"Gross spend by this fan across the agency's creators in the range, net of refunds and chargebacks. USD cents."},"net":{"type":"integer","description":"Net spend by this fan across the agency's creators in the range, net of refunds and chargebacks. USD cents."},"topCreator":{"type":["object","null"],"properties":{"uuid":{"type":"string","format":"uuid","description":"UUID of the creator"},"handle":{"type":"string","description":"Creator's handle on the platform"}},"required":["uuid","handle"],"description":"The agency creator this fan spent the most on in the date range, by the same earnings view, or null if it cannot be resolved"}},"required":["uuid","handle","displayName","avatarUrl","gross","net","topCreator"]},"description":"Highest-spending fans, best first, at most five rows"}},"required":["data"]},"example":{"data":[{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","handle":"alex-fan","displayName":"Alex Fan","avatarUrl":"https://media.fanvue.com/avatars/example-avatar.jpg","gross":124000,"net":105400,"topCreator":{"uuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","handle":"sarah-jones"}},{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","handle":"jordan-cool","displayName":"Jordan Cool","avatarUrl":null,"gross":86000,"net":73100,"topCreator":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<Info>Requires: Agency admin access</Info>","operationId":"listAgencyChats","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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":"date-time","description":"Incremental sync: only return chats with activity strictly after this timestamp. Chats with no messages are excluded."},"required":false,"description":"Incremental sync: only return chats with activity strictly after this timestamp. Chats with no messages are excluded.","name":"updatedAfter","in":"query"},{"schema":{"type":"string","enum":["most_recent_messages","online_now","most_unanswered_chats"],"description":"Sort order for the chat list (default: most_recent_messages)"},"required":false,"description":"Sort order for the chat list (default: most_recent_messages)","name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction for the chat list (default: desc)"},"required":false,"description":"Sort direction for the chat list (default: desc)","name":"sortDirection","in":"query"}],"security":[{"BearerAuth":["read:agency","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"],"format":"date"},"lastMessageAt":{"type":["string","null"],"format":"date","description":"Date of the last message in this chat"},"isRead":{"type":"boolean","description":"Whether the chat is read. Authoritative for unread badges: it is false either when unread messages exist or when the chat was manually marked unread via PATCH /chats/{userUuid}, in which case `unreadMessagesCount` stays 0."},"isMuted":{"type":"boolean"},"unreadMessagesCount":{"type":"number","description":"Number of messages in this chat the authenticated user has not read. 0 for a chat that was manually marked unread — use `isRead` for badge state."},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"lastMessage":{"type":["object","null"],"properties":{"text":{"type":["string","null"]},"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","null"],"format":"date"},"hasMedia":{"type":["boolean","null"]},"hasGif":{"type":"boolean","description":"Whether the last message is a GIF message. Its text may still be set as a caption. Fetch the message to get the GIF itself."},"mediaType":{"type":["string","null"],"enum":["image","video","audio","document"]},"senderUuid":{"type":"string","format":"uuid"},"senderRole":{"type":"string","enum":["FAN","CREATOR","AGENCY","SYSTEM"],"description":"Who sent the last message: CREATOR (the creator, sent directly), AGENCY (a team member sent it on the creator's behalf), FAN (the counterpart fan) or SYSTEM (an automated/platform message such as a subscription automation or KYC prompt)."},"sentByUserId":{"type":["string","null"],"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"},"status":{"type":["string","null"],"enum":["Sent","Delivered","Read"],"description":"Delivery status of the last message from the sender's perspective: Sent (still in flight), Delivered (sent but not yet read by the recipient) or Read. Null when the last message was received by the authenticated user (inbound)."}},"required":["text","type","uuid","sentAt","hasMedia","hasGif","mediaType","senderUuid","senderRole","sentByUserId"]},"isCreator":{"type":"boolean","description":"Whether the chat counterpart is also a creator on the platform"},"online":{"type":"boolean","description":"Whether the counterpart is currently online. Provided inline to avoid a separate /chats/statuses request."},"lastSeenAt":{"type":["string","null"],"format":"date","description":"When the counterpart was last seen online, or null if unknown/hidden"},"customLists":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Custom list UUID"},"name":{"type":"string","description":"Custom list name"}},"required":["uuid","name"]},"description":"Custom lists owned by the authenticated user that the counterpart belongs to"},"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,"hasGif":false,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","senderRole":"CREATOR","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"}}}},"/agencies/chats/messages/batch":{"post":{"summary":"Get messages from multiple chats in bulk across the agency's creators (POST batch)","description":"Returns the most recent messages for chats grouped by creator, across the creators the authenticated user's agency manages, in a single request.\n\nThis collapses the outer per-creator fan-out: instead of one batch call per managed creator (`POST /creators/{creatorUserUuid}/chats/messages/batch`), agencies send one request grouping chat UUIDs under each creator. Each creator group takes the same `chatUuids`, `sinceMessageUuid` and `limit` fields as the per-creator batch, so per-key behaviour is identical — just add the creator dimension.\n\nPer-creator and per-chat errors are reported inside the 200 response body, so a single forbidden/missing creator or chat never collapses the whole request. A creator the agency does not manage is returned as `{ \"error\": \"forbidden\" | \"not_found\" }` at the creator level.\n\n<Note>Maximum 50 chat UUIDs in total across all creators, and 25 creators per request.</Note>\n<Note>Read-only: fetching messages in bulk does not mutate read state — messages are not marked read and `isRead` reflects each message's state at read time.</Note>\n<Info>Requires: Agency admin access</Info>","operationId":"batchAgencyMessages","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:agency","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"creators":{"type":"array","items":{"type":"object","properties":{"chatUuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"description":"Array of chat UUIDs (counterpart user UUIDs) to fetch messages for (1-50)"},"sinceMessageUuid":{"type":"string","format":"uuid","description":"Optional cursor for incremental walks: returns only messages strictly after this message's publish date in each chat"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Maximum messages to return per chat (1-50, default: 20)"},"creatorUserUuid":{"type":"string","format":"uuid","description":"UUID of a creator the agency manages"}},"required":["chatUuids","creatorUserUuid"]},"minItems":1,"maxItems":25,"description":"Per-creator groups of chat UUIDs (1-25 creators)"}},"required":["creators"]}}}},"responses":{"200":{"description":"Per-creator, per-chat messages or error. Always 200 when the request itself is valid, even if every key fails.","content":{"application/json":{"schema":{"type":"object","properties":{"byCreator":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"byChat":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"text":{"type":["string","null"]},"sentAt":{"type":["string","null"],"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","null"]},"mediaType":{"type":["string","null"],"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)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the media item shown for free as a preview of this pay-to-view message, or null when no free preview was configured. Mirrors the `mediaPreviewUuid` set when sending the message."},"gif":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The GIF provider's durable identifier for this GIF. Stable across renditions; use it to de-duplicate or re-resolve the GIF."},"format":{"type":"string","enum":["GIF","WEBP","MP4","WEBM"],"description":"Encoding of the asset at `url`. Only `GIF` and `WEBP` are produced today, and both render in a plain <img> tag."},"title":{"type":["string","null"],"description":"Human-readable GIF title, suitable as alt text."},"url":{"type":["string","null"],"description":"Hotlink URL of the GIF, served from the provider's CDN — Fanvue does not host or proxy the asset. Null when the URL is temporarily withheld; the message is still a GIF message, so render a placeholder at `width`/`height` rather than treating it as empty."},"width":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic width of the asset at `url`, in pixels"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic height of the asset at `url`, in pixels"}},"required":["id","format","title","url","width","height"],"description":"The third-party GIF attached to this message, or null for an ordinary message. A GIF message carries no media and no price, but `text` may be set — a GIF can be sent with a caption."},"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"]},"pricing":{"type":["object","null"],"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","null"],"format":"date","description":"Timestamp when this message was purchased, or null if not purchased"},"tipSource":{"type":["string","null"],"enum":["chat","post","media_link"],"description":"For TIP messages, where the tip originated: 'chat' (direct in-chat tip), 'post' (tipped a feed post) or 'media_link' (tipped via a shared media link). Null for non-tip messages."},"sentByUserId":{"type":["string","null"],"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"},"appUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the third-party app that created this message through the public API. Null when the message was sent from the Fanvue dashboard, and for every message sent before app attribution was recorded."},"isRead":{"type":"boolean","description":"Whether the message has been read by the recipient"}},"required":["uuid","text","sentAt","sender","recipient","hasMedia","mediaType","mediaUuids","mediaPreviewUuid","gif","type","pricing","purchasedAt","tipSource","sentByUserId","appUuid","isRead"]}},"hasMore":{"type":"boolean","description":"Whether more messages exist beyond the returned set (older than `oldestMessageUuid` for the default newest-first read, or in the queried range for incremental walks)"},"oldestMessageUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the oldest message in the returned batch, or null if no messages were returned"}},"required":["messages","hasMore","oldestMessageUuid"]},{"type":"object","properties":{"error":{"type":"string","enum":["forbidden","not_found","internal"]}},"required":["error"]}]},"description":"Map of input chat UUID to messages or a per-key error"}},"required":["byChat"]},{"type":"object","properties":{"error":{"type":"string","enum":["forbidden","not_found","internal"]}},"required":["error"]}]},"description":"Map of input creator UUID to its per-chat messages, or a creator-level error (forbidden/not_found)."}},"required":["byCreator"]},"example":{"byCreator":{"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8":{"byChat":{"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7":{"messages":[{"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":[],"mediaPreviewUuid":null,"gif":null,"pricing":null,"purchasedAt":null,"sentByUserId":null,"appUuid":"f6a7b8c9-0123-4567-89ab-cdef01234567","isRead":true}],"hasMore":true,"oldestMessageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"},"c3d4e5f6-7890-1234-5678-9abcdef01234":{"error":"not_found"}}},"22222222-2222-4222-8222-222222222222":{"error":"forbidden"}}}}}},"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/subscribers":{"get":{"summary":"List active subscribers across all agency creators","description":"Returns a single paginated stream of active subscriptions across every creator the authenticated agency manages, sorted by most recent subscription first. 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}/subscribers` fan-out used by agency CRM sync flows: 1 + N calls collapse to ceil(total/size) calls.\n<Info>Requires: Agency admin access</Info>","operationId":"listAgencySubscribers","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Comma-separated list of creator UUIDs (max 50)"},"required":false,"description":"Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50)","name":"creatorUuids","in":"query","style":"form","explode":false}],"security":[{"BearerAuth":["read:agency","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Paginated list of active subscribers across the agency's 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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"},"creatorUuid":{"type":"string","format":"uuid","description":"UUID of the agency-managed creator that the subscriber is subscribed to"},"subscribedAt":{"type":"string","format":"date-time","description":"When the subscription was created"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the subscription is scheduled to expire, if applicable"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt","creatorUuid","subscribedAt","expiresAt"]},"description":"Array of active subscribers 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":[{"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","creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","subscribedAt":"2024-01-15T00:00:00.000Z","expiresAt":null},{"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","creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r9","subscribedAt":"2024-01-14T00:00:00.000Z","expiresAt":"2024-01-15T00:00:00.000Z"}],"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"}}}},"/agencies/earnings":{"get":{"summary":"List per-creator-per-day earnings across all agency creators","description":"Returns a single paginated stream of per-creator-per-day earnings rows across every creator the authenticated agency manages, sorted by most recent day first. Each row is bucketed by `paid_at` (UTC) and tagged with `creatorUuid` so consumers can group results without an additional join.\n\nOnly PAID earning invoices that count towards creator insights are included. Each `gross`/`net` figure is the sum of the day's invoices in USD cents (`currency` is always `\"USD\"`), so totals reconcile with the USD figure shown on the dashboard.\n<Info>Requires: Agency admin access</Info>","operationId":"listAgencyEarningsByDay","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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":"date-time","description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Comma-separated list of creator UUIDs (max 50)"},"required":false,"description":"Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50)","name":"creatorUuids","in":"query","style":"form","explode":false}],"security":[{"BearerAuth":["read:agency","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Paginated list of per-creator-per-day earnings across the agency's creators","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"creatorUuid":{"type":"string","format":"uuid","description":"UUID of the agency-managed creator the earnings row belongs to"},"date":{"type":"string","format":"date","description":"UTC calendar day the earnings were bucketed on (YYYY-MM-DD)"},"gross":{"type":"integer","description":"Total gross earnings for the creator on this day, in USD cents"},"net":{"type":"integer","description":"Total creator-net earnings (after platform fees) for the creator on this day, in USD cents"},"currency":{"type":"string","enum":["USD"],"description":"Always 'USD'. Earnings are summed in USD across all of the day's invoices regardless of the local currency the fan originally paid in, so the figure reconciles with the USD dashboard total."}},"required":["creatorUuid","date","gross","net","currency"]},"description":"Array of per-creator-per-day earnings rows 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":[{"creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","date":"2024-01-15","gross":15000,"net":12750,"currency":"USD"},{"creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r9","date":"2024-01-14","gross":8500,"net":7225,"currency":"USD"}],"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"}}}},"/agencies/subscribers-history":{"get":{"summary":"List per-creator-per-day subscriber events across all agency creators","description":"Returns a single paginated stream of per-creator-per-day subscriber event rows across every creator the authenticated agency manages, sorted by most recent day first.\n\nThis endpoint is an analytics time series, not a real-time audience snapshot:\n- `newSubscribersCount` = number of new subscription starts in the day bucket for the creator\n- `cancelledSubscribersCount` = number of subscription chain ends in the day bucket for the creator\n- `total` = cumulative net change for the creator from the beginning of the requested range (`new - cancelled`)\n- `renewalOnCount` = auto-renewing (paid, recurring) subscriptions that started in the day bucket\n- `renewalOffCount` = subscriptions whose auto-renewal was switched off in the day bucket\n- `freeTrialCount` = free-trial subscriptions that started in the day bucket\n- `expiredCount` = subscriptions that lapsed (expired) in the day bucket\n\n`newSubscribersCount`/`cancelledSubscribersCount`/`renewalOnCount`/`freeTrialCount`/`total` are derived from paid invoices (immutable, stable across resubscriptions). `renewalOffCount`/`expiredCount` are derived from the subscriptions table (`cancelled_at`/`deleted_at`) — both fields are cleared on resubscribe, so these counts may be zero for subscriptions that were later reactivated. `expiredCount` may also differ slightly from `cancelledSubscribersCount` since they measure lapse from different sources.\n\n`newSubscribersCount` counts subscription **starts**, not distinct people: a returning fan who starts a new subscription is counted again. It also includes free trials, starts later refunded or charged back, fans who were later banned or deleted, and it spans profile subscriptions, checkout-link subscriptions and fan-experience subscriptions. Because of this it is normally higher than the \"New\" figure on the creator's in-app Insights dashboard, which counts first-ever profile subscribers only.\n\nDays are **UTC calendar days**. `startDate`/`endDate` offsets are honoured when selecting the window, but there is no timezone parameter, so a creator working in a non-UTC timezone should expect their local-day totals to differ from these buckets.\n\n`freeTrialCount` + `renewalOnCount` always equals `newSubscribersCount` — every start is classified as one or the other from the invoice's subscription type. A creator who only sells free trials will therefore see `freeTrialCount` equal to `newSubscribersCount` on every row; that is expected, not a duplicated field.\n\nIf you need the current list of subscribers for messaging or CRM sync, use `GET /agencies/subscribers` instead.\n<Info>Requires: Agency admin access</Info>","operationId":"listAgencySubscribersHistory","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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":"date-time","description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset. Range must not exceed 365 days."},"required":true,"description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset. Range must not exceed 365 days.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Comma-separated list of creator UUIDs (max 50)"},"required":false,"description":"Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50)","name":"creatorUuids","in":"query","style":"form","explode":false}],"security":[{"BearerAuth":["read:agency","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Paginated list of per-creator-per-day subscriber events across the agency's creators","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"creatorUuid":{"type":"string","format":"uuid","description":"UUID of the agency-managed creator the row belongs to"},"date":{"type":"string","format":"date","description":"UTC calendar day the events are bucketed on (YYYY-MM-DD)"},"total":{"type":"integer","description":"Cumulative net change in active subscribers for this creator from the start of the requested range (newSubscribersCount - cancelledSubscribersCount, running)"},"newSubscribersCount":{"type":"integer","minimum":0,"description":"Number of new subscription chains started on this day for this creator"},"cancelledSubscribersCount":{"type":"integer","minimum":0,"description":"Number of subscription chains ending (final non-renewing expiry) on this day for this creator"},"renewalOnCount":{"type":"integer","minimum":0,"description":"Number of auto-renewing (paid, recurring) subscriptions that started on this day for this creator. A subscription has auto-renew on when created, so this counts non-free-trial starts."},"renewalOffCount":{"type":"integer","minimum":0,"description":"Number of subscriptions whose auto-renewal was switched off on this day for this creator. The subscription stays active until it expires."},"freeTrialCount":{"type":"integer","minimum":0,"description":"Number of free-trial subscriptions that started on this day for this creator"},"expiredCount":{"type":"integer","minimum":0,"description":"Number of subscriptions that lapsed (expired) on this day for this creator. Derived from the subscriptions table, so it may differ slightly from cancelledSubscribersCount, which derives the same notion from the invoice chain."}},"required":["creatorUuid","date","total","newSubscribersCount","cancelledSubscribersCount","renewalOnCount","renewalOffCount","freeTrialCount","expiredCount"]},"description":"Array of per-creator-per-day subscriber event rows 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":[{"creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","date":"2024-01-15","total":5,"newSubscribersCount":6,"cancelledSubscribersCount":1,"renewalOnCount":5,"renewalOffCount":2,"freeTrialCount":1,"expiredCount":1},{"creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r9","date":"2024-01-14","total":2,"newSubscribersCount":3,"cancelledSubscribersCount":1,"renewalOnCount":2,"renewalOffCount":1,"freeTrialCount":1,"expiredCount":1}],"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"}}}},"/agencies/followers-history":{"get":{"summary":"List per-creator-per-day new-follower counts across all agency creators","description":"Returns a single paginated stream of per-creator-per-day new-follower rows across every creator the authenticated agency manages, sorted by most recent day first.\n\nThis endpoint is an analytics time series, not a real-time audience snapshot:\n- `newFollowersCount` = number of new follows recorded in the day bucket for the creator\n- `total` = cumulative new followers for the creator from the beginning of the requested range (running sum of `newFollowersCount`)\n\n<Warning>Follows are hard-deleted on unfollow — there is no record of unfollows. As a result this series only counts follows that still exist, has no unfollow/net-loss column, and historical days are survivorship-biased (a follow that was later undone leaves no trace). `total` is therefore cumulative new follows gained within the range, **not** an absolute or net follower count. For the current follower count, use the account/audience endpoints instead.</Warning>\n\n<Info>Requires: Agency admin access</Info>","operationId":"listAgencyFollowersHistory","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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":"date-time","description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset."},"required":true,"description":"Start of the date range (inclusive). UTC ISO 8601 datetime with offset.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset. Range must not exceed 365 days."},"required":true,"description":"End of the date range (exclusive). UTC ISO 8601 datetime with offset. Range must not exceed 365 days.","name":"endDate","in":"query"},{"schema":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Comma-separated list of creator UUIDs (max 50)"},"required":false,"description":"Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50)","name":"creatorUuids","in":"query","style":"form","explode":false}],"security":[{"BearerAuth":["read:agency","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:agency` — Read agency information, including the agency's team members.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Paginated list of per-creator-per-day new-follower counts across the agency's creators","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"creatorUuid":{"type":"string","format":"uuid","description":"UUID of the agency-managed creator the row belongs to"},"date":{"type":"string","format":"date","description":"UTC calendar day the new follows are bucketed on (YYYY-MM-DD)"},"total":{"type":"integer","minimum":0,"description":"Cumulative new followers for this creator from the start of the requested range (running sum of newFollowersCount). Not an absolute follower count: it excludes followers gained before the range and cannot account for unfollows (see newFollowersCount)."},"newFollowersCount":{"type":"integer","minimum":0,"description":"Number of new follows recorded on this day for this creator. Survivorship-biased: follows that were later undone are hard-deleted with no trace, so historical days only count follows that still exist today."}},"required":["creatorUuid","date","total","newFollowersCount"]},"description":"Array of per-creator-per-day new-follower rows 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":[{"creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","date":"2024-01-15","total":14,"newFollowersCount":6},{"creatorUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r9","date":"2024-01-14","total":8,"newFollowersCount":3}],"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"}}}},"/apps":{"get":{"summary":"List published app store apps","description":"Returns the published App Store listings with their marketing metadata (title, tagline, description, pricing type, rating summary, logo and developer). Use `search` to filter and paginate for discovery.","operationId":"listAppStoreListings","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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":"Case-insensitive filter matched against the app's listing metadata."},"required":false,"description":"Case-insensitive filter matched against the app's listing metadata.","name":"search","in":"query"}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Paginated list of published app store apps","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","description":"User-facing app title."},"tagline":{"type":"string"},"description":{"type":"string","description":"Marketing description of the app."},"logoUrl":{"type":"string"},"appUrl":{"type":["string","null"]},"pricingType":{"type":"string","enum":["free","monthly"]},"rating":{"type":"object","properties":{"average":{"type":["number","null"],"description":"Weighted average rating (1-5), or null until the app has enough ratings to show."},"count":{"type":["number","null"],"description":"Number of genuine ratings, or null until the app has enough to show."}},"required":["average","count"]},"developer":{"type":"object","properties":{"name":{"type":["string","null"],"description":"The developer's public display name."},"handle":{"type":["string","null"],"description":"The developer's public Fanvue handle."}},"required":["name","handle"]}},"required":["uuid","name","tagline","description","logoUrl","appUrl","pricingType","rating","developer"]},"description":"Array of app listings"},"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":"00000000-0000-4000-8000-000000000001","name":"Content Studio","tagline":"AI-assisted content generation for creators","description":"Generate captions, ideas and post drafts tailored to your audience.","logoUrl":"https://cdn.fanvue.com/app-store/content-studio/logo.png","appUrl":"https://contentstudio.example.com","pricingType":"monthly","rating":{"average":4.6,"count":128},"developer":{"name":"Content Studio Inc.","handle":"contentstudio"}}],"pagination":{"page":1,"size":1,"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"},"502":{"description":"Failed to load app listings from upstream","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"503":{"description":"App store upstream is not configured","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/apps/{appUuid}":{"get":{"summary":"Get a published app store app's full listing","description":"Returns the full listing for a single published app: description body, highlights, screenshots, pricing plans and rating distribution.","operationId":"getAppStoreListing","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"The app's full store listing","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","description":"User-facing app title."},"tagline":{"type":"string"},"description":{"type":"string","description":"Marketing description of the app."},"logoUrl":{"type":"string"},"appUrl":{"type":["string","null"]},"pricingType":{"type":"string","enum":["free","monthly"]},"rating":{"type":"object","properties":{"average":{"type":["number","null"],"description":"Weighted average rating (1-5), or null until the app has enough ratings to show."},"count":{"type":["number","null"],"description":"Number of genuine ratings, or null until the app has enough to show."}},"required":["average","count"]},"developer":{"type":"object","properties":{"name":{"type":["string","null"],"description":"The developer's public display name."},"handle":{"type":["string","null"],"description":"The developer's public Fanvue handle."}},"required":["name","handle"]},"descriptionTitle":{"type":"string"},"descriptionBody":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}},"heroImageUrl":{"type":"string"},"previewImageUrls":{"type":"array","items":{"type":"string"}},"galleryImageUrls":{"type":"array","items":{"type":"string"}},"pricingPlans":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"billingType":{"type":"string","enum":["free","one_time","recurring"]},"interval":{"type":["string","null"],"enum":["monthly","yearly"]},"price":{"type":"number","description":"Price in minor currency units (e.g. cents). 0 for free plans."},"currencyCode":{"type":"string"},"status":{"type":"string","enum":["pending_setup","active","withdrawn"]},"highlights":{"type":"array","items":{"type":"string"},"description":"Marketing feature bullets for this plan's store card."}},"required":["uuid","name","description","billingType","interval","price","currencyCode","status","highlights"]}},"ratingDistribution":{"type":["array","null"],"items":{"type":"object","properties":{"rating":{"type":"integer","minimum":1,"maximum":5},"proportion":{"type":"number","description":"Share of genuine ratings at this star, 0..1."},"count":{"type":["number","null"],"description":"Genuine count at this star, or null below the floor."}},"required":["rating","proportion","count"]}}},"required":["uuid","name","tagline","description","logoUrl","appUrl","pricingType","rating","developer","descriptionTitle","descriptionBody","highlights","heroImageUrl","previewImageUrls","galleryImageUrls","pricingPlans","ratingDistribution"]},"example":{"uuid":"00000000-0000-4000-8000-000000000001","name":"Content Studio","tagline":"AI-assisted content generation for creators","description":"Generate captions, ideas and post drafts tailored to your audience.","logoUrl":"https://cdn.fanvue.com/app-store/content-studio/logo.png","appUrl":"https://contentstudio.example.com","pricingType":"monthly","rating":{"average":4.6,"count":128},"developer":{"name":"Content Studio Inc.","handle":"contentstudio"},"descriptionTitle":"Create more, faster","descriptionBody":"Content Studio turns a few prompts into ready-to-post captions, hooks and ideas, all matched to your voice.","highlights":["AI captions","Idea generator","Brand voice matching"],"heroImageUrl":"https://cdn.fanvue.com/app-store/content-studio/hero.png","previewImageUrls":["https://cdn.fanvue.com/app-store/content-studio/preview-1.png"],"galleryImageUrls":["https://cdn.fanvue.com/app-store/content-studio/gallery-1.png"],"pricingPlans":[{"uuid":"00000000-0000-4000-8000-000000000002","name":"Pro Monthly","description":"Everything you need to scale your content.","billingType":"recurring","interval":"monthly","price":999,"currencyCode":"USD","status":"active","highlights":["Unlimited generations","Priority support"]}],"ratingDistribution":[{"rating":5,"proportion":0.72,"count":92},{"rating":4,"proportion":0.18,"count":23},{"rating":3,"proportion":0.06,"count":8},{"rating":2,"proportion":0.02,"count":3},{"rating":1,"proportion":0.02,"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":{"description":"App not found or not published","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 app listings from upstream","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"503":{"description":"App store upstream is not configured","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/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`).","operationId":"getAppSubscriptionStatus","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"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","null"],"enum":["monthly","yearly"]},"price":{"type":"number"},"currencyCode":{"type":"string"},"status":{"type":"string","enum":["pending_setup","active","withdrawn"]},"checkoutUrl":{"type":["string","null"],"format":"uri"}},"required":["uuid","name","billingType","interval","price","currencyCode","status","checkoutUrl"]}}},"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","checkoutUrl":null},{"uuid":"00000000-0000-4000-8000-000000000005","name":"Yearly","billingType":"recurring","interval":"yearly","price":9990,"currencyCode":"USD","status":"active","checkoutUrl":"https://www.fanvue.com/checkout/app_000000001VgEh72lXvTXkL"}]}}}},"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    A `status: \"pending\"` entry with `currentPeriodEnd: null` is a checkout awaiting payment: the user is not entitled to the plan yet, so `planUuid` and `planName` are `null` until the payment settles. A `pending` entry with a non-null `currentPeriodEnd` is a paid subscription with an in-flight cancellation and keeps its plan fields.","operationId":"getAppCurrentUserSubscription","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"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","null"],"format":"uuid"},"planName":{"type":["string","null"]},"currentPeriodEnd":{"type":["string","null"]},"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","null"],"format":"uuid"},"planName":{"type":["string","null"]},"currentPeriodEnd":{"type":["string","null"]},"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"}}}}}}}}},"/apps/{appUuid}/payments/me":{"get":{"summary":"List the authenticated user's one-time (app-OTP) payments for an app","description":"`read:self`. Returns only the authenticated user's own one-time payments for an app; filtered to the caller's identity, never owner-gated, so it cannot surface another buyer's data.","operationId":"getMyAppPayments","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"description":"Number of results to return (default 50, max 100)."},"required":false,"description":"Number of results to return (default 50, max 100).","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor for the next page, from a prior response."},"required":false,"description":"Opaque cursor for the next page, from a prior response.","name":"cursor","in":"query"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"200":{"description":"List of the user's one-time payments for the app","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","description":"Horizon purchase identifier."},"appUuid":{"type":"string","description":"UUID of the app the purchase belongs to."},"buyerUuid":{"type":"string","description":"UUID of the purchasing Fanvue user."},"planUuid":{"type":"string","description":"UUID of the purchased pricing plan / item."},"invoiceNumber":{"type":["string","null"],"description":"Fanvue invoice number. Use as the idempotency key for fulfilment. Null for purchases that settled before reconciliation was enabled, or not yet settled."},"billingReferenceId":{"type":"string","description":"The `appotp_…` reference minted at checkout."},"clientReferenceId":{"type":"string","description":"Merchant-supplied reference passed at checkout via `?client_reference_id=`; empty string when unset."},"status":{"type":"string","enum":["pending","completed","failed","refunded","expired"],"description":"Lifecycle status of the one-time purchase."},"amount":{"type":"number","description":"Amount in minor currency units, snapshotted at checkout."},"currency":{"type":"string","description":"ISO currency code."},"externalPaymentId":{"type":"string","description":"Provider payment id; empty string until completed."},"createdAt":{"type":"string","format":"date-time","description":"When the purchase was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the purchase was last updated."}},"required":["uuid","appUuid","buyerUuid","planUuid","invoiceNumber","billingReferenceId","clientReferenceId","status","amount","currency","externalPaymentId","createdAt","updatedAt"]}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null if none."}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"00000000-0000-4000-8000-0000000000aa","appUuid":"00000000-0000-4000-8000-000000000001","buyerUuid":"00000000-0000-4000-8000-000000000003","planUuid":"00000000-0000-4000-8000-000000000002","invoiceNumber":"FVE-20260619-1234","billingReferenceId":"appotp_000000001VgEh72lXvTXkL","clientReferenceId":"order_9f8c","status":"completed","amount":4999,"currency":"USD","externalPaymentId":"pi_3Q1example","createdAt":"2026-06-19T08:30:00.000Z","updatedAt":"2026-06-19T08:30:05.000Z"}],"nextCursor":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":{"description":"App not found / not owned, or payment not found","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 payments 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}/payments/me/{invoiceNumber}":{"get":{"summary":"Get the authenticated user's one-time (app-OTP) payment by invoice number","description":"`read:self`. Fetches one of the caller's own payments by Fanvue invoice number. 404 for unknown invoice numbers, another buyer's payment, or pre-migration rows.","operationId":"getMyAppPaymentByInvoiceNumber","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"},{"schema":{"type":"string","example":"FVE-20260619-1234"},"required":true,"name":"invoiceNumber","in":"path"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"200":{"description":"The user's one-time payment","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","description":"Horizon purchase identifier."},"appUuid":{"type":"string","description":"UUID of the app the purchase belongs to."},"buyerUuid":{"type":"string","description":"UUID of the purchasing Fanvue user."},"planUuid":{"type":"string","description":"UUID of the purchased pricing plan / item."},"invoiceNumber":{"type":["string","null"],"description":"Fanvue invoice number. Use as the idempotency key for fulfilment. Null for purchases that settled before reconciliation was enabled, or not yet settled."},"billingReferenceId":{"type":"string","description":"The `appotp_…` reference minted at checkout."},"clientReferenceId":{"type":"string","description":"Merchant-supplied reference passed at checkout via `?client_reference_id=`; empty string when unset."},"status":{"type":"string","enum":["pending","completed","failed","refunded","expired"],"description":"Lifecycle status of the one-time purchase."},"amount":{"type":"number","description":"Amount in minor currency units, snapshotted at checkout."},"currency":{"type":"string","description":"ISO currency code."},"externalPaymentId":{"type":"string","description":"Provider payment id; empty string until completed."},"createdAt":{"type":"string","format":"date-time","description":"When the purchase was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the purchase was last updated."}},"required":["uuid","appUuid","buyerUuid","planUuid","invoiceNumber","billingReferenceId","clientReferenceId","status","amount","currency","externalPaymentId","createdAt","updatedAt"]},"example":{"uuid":"00000000-0000-4000-8000-0000000000aa","appUuid":"00000000-0000-4000-8000-000000000001","buyerUuid":"00000000-0000-4000-8000-000000000003","planUuid":"00000000-0000-4000-8000-000000000002","invoiceNumber":"FVE-20260619-1234","billingReferenceId":"appotp_000000001VgEh72lXvTXkL","clientReferenceId":"order_9f8c","status":"completed","amount":4999,"currency":"USD","externalPaymentId":"pi_3Q1example","createdAt":"2026-06-19T08:30:00.000Z","updatedAt":"2026-06-19T08:30:05.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":{"description":"App not found / not owned, or payment not found","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 payments 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}/payments":{"get":{"summary":"List one-time (app-OTP) payments for a developer-owned app","description":"Owner-only. Returns one-time payments across all buyers for an app the authenticated developer owns; gated on app ownership. Distinct from `/payments/me` (`read:self`) by design — collapsing them would expose every customer's payments to a buyer token.","operationId":"getAppPayments","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"description":"Number of results to return (default 50, max 100)."},"required":false,"description":"Number of results to return (default 50, max 100).","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor for the next page, from a prior response."},"required":false,"description":"Opaque cursor for the next page, from a prior response.","name":"cursor","in":"query"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"200":{"description":"List of one-time payments for the app","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","description":"Horizon purchase identifier."},"appUuid":{"type":"string","description":"UUID of the app the purchase belongs to."},"buyerUuid":{"type":"string","description":"UUID of the purchasing Fanvue user."},"planUuid":{"type":"string","description":"UUID of the purchased pricing plan / item."},"invoiceNumber":{"type":["string","null"],"description":"Fanvue invoice number. Use as the idempotency key for fulfilment. Null for purchases that settled before reconciliation was enabled, or not yet settled."},"billingReferenceId":{"type":"string","description":"The `appotp_…` reference minted at checkout."},"clientReferenceId":{"type":"string","description":"Merchant-supplied reference passed at checkout via `?client_reference_id=`; empty string when unset."},"status":{"type":"string","enum":["pending","completed","failed","refunded","expired"],"description":"Lifecycle status of the one-time purchase."},"amount":{"type":"number","description":"Amount in minor currency units, snapshotted at checkout."},"currency":{"type":"string","description":"ISO currency code."},"externalPaymentId":{"type":"string","description":"Provider payment id; empty string until completed."},"createdAt":{"type":"string","format":"date-time","description":"When the purchase was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the purchase was last updated."}},"required":["uuid","appUuid","buyerUuid","planUuid","invoiceNumber","billingReferenceId","clientReferenceId","status","amount","currency","externalPaymentId","createdAt","updatedAt"]}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null if none."}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"00000000-0000-4000-8000-0000000000aa","appUuid":"00000000-0000-4000-8000-000000000001","buyerUuid":"00000000-0000-4000-8000-000000000003","planUuid":"00000000-0000-4000-8000-000000000002","invoiceNumber":"FVE-20260619-1234","billingReferenceId":"appotp_000000001VgEh72lXvTXkL","clientReferenceId":"order_9f8c","status":"completed","amount":4999,"currency":"USD","externalPaymentId":"pi_3Q1example","createdAt":"2026-06-19T08:30:00.000Z","updatedAt":"2026-06-19T08:30:05.000Z"}],"nextCursor":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":{"description":"App not found / not owned, or payment not found","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 payments 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}/payments/{invoiceNumber}":{"get":{"summary":"Get a one-time (app-OTP) payment by invoice number for a developer-owned app","description":"Owner-only. Fetches a single payment (any buyer's) by Fanvue invoice number for an app the developer owns. 404 for unknown/pre-migration invoice numbers.","operationId":"getAppPaymentByInvoiceNumber","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"appUuid","in":"path"},{"schema":{"type":"string","example":"FVE-20260619-1234"},"required":true,"name":"invoiceNumber","in":"path"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"200":{"description":"The one-time payment","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","description":"Horizon purchase identifier."},"appUuid":{"type":"string","description":"UUID of the app the purchase belongs to."},"buyerUuid":{"type":"string","description":"UUID of the purchasing Fanvue user."},"planUuid":{"type":"string","description":"UUID of the purchased pricing plan / item."},"invoiceNumber":{"type":["string","null"],"description":"Fanvue invoice number. Use as the idempotency key for fulfilment. Null for purchases that settled before reconciliation was enabled, or not yet settled."},"billingReferenceId":{"type":"string","description":"The `appotp_…` reference minted at checkout."},"clientReferenceId":{"type":"string","description":"Merchant-supplied reference passed at checkout via `?client_reference_id=`; empty string when unset."},"status":{"type":"string","enum":["pending","completed","failed","refunded","expired"],"description":"Lifecycle status of the one-time purchase."},"amount":{"type":"number","description":"Amount in minor currency units, snapshotted at checkout."},"currency":{"type":"string","description":"ISO currency code."},"externalPaymentId":{"type":"string","description":"Provider payment id; empty string until completed."},"createdAt":{"type":"string","format":"date-time","description":"When the purchase was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the purchase was last updated."}},"required":["uuid","appUuid","buyerUuid","planUuid","invoiceNumber","billingReferenceId","clientReferenceId","status","amount","currency","externalPaymentId","createdAt","updatedAt"]},"example":{"uuid":"00000000-0000-4000-8000-0000000000aa","appUuid":"00000000-0000-4000-8000-000000000001","buyerUuid":"00000000-0000-4000-8000-000000000003","planUuid":"00000000-0000-4000-8000-000000000002","invoiceNumber":"FVE-20260619-1234","billingReferenceId":"appotp_000000001VgEh72lXvTXkL","clientReferenceId":"order_9f8c","status":"completed","amount":4999,"currency":"USD","externalPaymentId":"pi_3Q1example","createdAt":"2026-06-19T08:30:00.000Z","updatedAt":"2026-06-19T08:30:05.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":{"description":"App not found / not owned, or payment not found","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 payments 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.","operationId":"createChat","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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- `muted` - Only 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**Sort Direction** (via `sortDirection` parameter):\n- `desc` (default) - Highest-ranked chats first (most recent / most online / most unanswered)\n- `asc` - Reverses the order (least recent / least online / fewest unanswered)\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","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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","format":"uuid"},"maxItems":100,"description":"Filter chats to these counterpart (fan) user UUIDs (repeat the param for multiple, max 100)"},"required":false,"description":"Filter chats to these counterpart (fan) user UUIDs (repeat the param for multiple, max 100)","name":"userUuids","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","creators"]},"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","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"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction for chat list (default: desc)"},"required":false,"description":"Sort direction for chat list (default: desc)","name":"sortDirection","in":"query"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"responses":{"200":{"description":"List of chats","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date"},"lastMessageAt":{"type":["string","null"],"format":"date","description":"Date of the last message in this chat"},"isRead":{"type":"boolean","description":"Whether the chat is read. Authoritative for unread badges: it is false either when unread messages exist or when the chat was manually marked unread via PATCH /chats/{userUuid}, in which case `unreadMessagesCount` stays 0."},"isMuted":{"type":"boolean"},"unreadMessagesCount":{"type":"number","description":"Number of messages in this chat the authenticated user has not read. 0 for a chat that was manually marked unread — use `isRead` for badge state."},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"lastMessage":{"type":["object","null"],"properties":{"text":{"type":["string","null"]},"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","null"],"format":"date"},"hasMedia":{"type":["boolean","null"]},"hasGif":{"type":"boolean","description":"Whether the last message is a GIF message. Its text may still be set as a caption. Fetch the message to get the GIF itself."},"mediaType":{"type":["string","null"],"enum":["image","video","audio","document"]},"senderUuid":{"type":"string","format":"uuid"},"senderRole":{"type":"string","enum":["FAN","CREATOR","AGENCY","SYSTEM"],"description":"Who sent the last message: CREATOR (the creator, sent directly), AGENCY (a team member sent it on the creator's behalf), FAN (the counterpart fan) or SYSTEM (an automated/platform message such as a subscription automation or KYC prompt)."},"sentByUserId":{"type":["string","null"],"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"},"status":{"type":["string","null"],"enum":["Sent","Delivered","Read"],"description":"Delivery status of the last message from the sender's perspective: Sent (still in flight), Delivered (sent but not yet read by the recipient) or Read. Null when the last message was received by the authenticated user (inbound)."}},"required":["text","type","uuid","sentAt","hasMedia","hasGif","mediaType","senderUuid","senderRole","sentByUserId"]},"isCreator":{"type":"boolean","description":"Whether the chat counterpart is also a creator on the platform"},"online":{"type":"boolean","description":"Whether the counterpart is currently online. Provided inline to avoid a separate /chats/statuses request."},"lastSeenAt":{"type":["string","null"],"format":"date","description":"When the counterpart was last seen online, or null if unknown/hidden"},"customLists":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Custom list UUID"},"name":{"type":"string","description":"Custom list name"}},"required":["uuid","name"]},"description":"Custom lists owned by the authenticated user that the counterpart belongs to"}},"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"},"isCreator":false,"online":true,"lastSeenAt":"2024-01-15T00:00:00.000Z","customLists":[{"uuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","name":"VIPs"}],"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,"hasGif":false,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","senderRole":"CREATOR","sentByUserId":null,"status":"Read"}},{"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,"hasGif":false,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","senderRole":"CREATOR","sentByUserId":null,"status":"Delivered"}}],"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, or a single third-party GIF (`gif`) in place of text and media.","operationId":"sendMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":["string","null"],"minLength":1,"maxLength":5000},"gif":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The GIF provider's durable identifier for this GIF (as returned on a GIF message)"},"format":{"type":"string","enum":["GIF","WEBP"],"description":"Encoding of the asset at `url`"},"title":{"type":["string","null"],"description":"Human-readable GIF title, used as alt text. Accepts null as well as omission, so the `gif` block returned by a read can be sent back unchanged."},"url":{"type":"string","format":"uri","description":"Hotlink URL of the GIF on the provider's CDN"},"width":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic width of the asset at `url`, in pixels"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic height of the asset at `url`, in pixels"}},"required":["id","format","url","width","height"],"description":"A third-party GIF to send in place of media. May be sent on its own or alongside `text`, which is rendered as a caption. Cannot be combined with `mediaUuids`, `mediaPreviewUuid`, `price` or `templateUuid`."},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"}},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of a single media item shown for free as a preview of a pay-to-view message. Requires a price and attached media (or a template)."},"price":{"type":["number","null"],"minimum":300},"templateUuid":{"type":["string","null"],"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}/typing":{"post":{"summary":"Send a typing indicator","description":"Signal that you are typing (or have stopped typing) in a chat with a user. The signal is delivered to the counterpart's realtime connection and is not persisted, so delivery is best-effort. Send an empty body `{}` (or omit `isTyping`) to indicate you are typing.","operationId":"setTyping","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isTyping":{"type":"boolean","default":true,"description":"Whether the caller is currently typing (true) or has stopped (false). Defaults to true."}}}}}},"responses":{"202":{"description":"Typing signal accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]},"example":{"success":true}}}},"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"}}}},"/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\nPass `beforeMessageUuid` to anchor pagination to a known message and fetch the messages immediately older than it (stable keyset pagination). When supplied, `beforeMessageUuid` takes precedence over `page`; an unknown or unpublished anchor is ignored and the first page is returned.\n\nPass `startDate` and/or `endDate` to restrict results to a time window on the message publish date. Both are optional and combine with `page`/`size` pagination. Both bounds are exclusive: `startDate` returns messages published strictly after it, `endDate` messages published strictly before it. This is the recommended way to fetch \"what changed since X\" instead of paging blindly after a mass message.\n\nNote that `endDate` suppresses `markAsRead`: because an upper-bounded window deliberately excludes the newest messages, marking the conversation read would clear unread state on messages this call never returned. Requests carrying `endDate` therefore never mark the chat as read, whatever `markAsRead` is set to.\n\n<Info>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.message.received`, `creator.message.sent`, `creator.message.deleted`, `creator.message.reaction` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/messages).\n</Info>","operationId":"listMessages","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"},{"schema":{"type":"string","format":"uuid","description":"Anchor cursor: return messages older than this message UUID. Takes precedence over `page`."},"required":false,"description":"Anchor cursor: return messages older than this message UUID. Takes precedence over `page`.","name":"beforeMessageUuid","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only return messages published after this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Exclusive lower bound. Combines with `page`/`size`."},"required":false,"description":"Only return messages published after this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Exclusive lower bound. Combines with `page`/`size`.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only return messages published before this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - messages before this date are included. Combines with `page`/`size`."},"required":false,"description":"Only return messages published before this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - messages before this date are included. Combines with `page`/`size`.","name":"endDate","in":"query"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"]},"sentAt":{"type":["string","null"],"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","null"]},"mediaType":{"type":["string","null"],"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)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the media item shown for free as a preview of this pay-to-view message, or null when no free preview was configured. Mirrors the `mediaPreviewUuid` set when sending the message."},"gif":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The GIF provider's durable identifier for this GIF. Stable across renditions; use it to de-duplicate or re-resolve the GIF."},"format":{"type":"string","enum":["GIF","WEBP","MP4","WEBM"],"description":"Encoding of the asset at `url`. Only `GIF` and `WEBP` are produced today, and both render in a plain <img> tag."},"title":{"type":["string","null"],"description":"Human-readable GIF title, suitable as alt text."},"url":{"type":["string","null"],"description":"Hotlink URL of the GIF, served from the provider's CDN — Fanvue does not host or proxy the asset. Null when the URL is temporarily withheld; the message is still a GIF message, so render a placeholder at `width`/`height` rather than treating it as empty."},"width":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic width of the asset at `url`, in pixels"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic height of the asset at `url`, in pixels"}},"required":["id","format","title","url","width","height"],"description":"The third-party GIF attached to this message, or null for an ordinary message. A GIF message carries no media and no price, but `text` may be set — a GIF can be sent with a caption."},"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"]},"pricing":{"type":["object","null"],"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","null"],"format":"date","description":"Timestamp when this message was purchased, or null if not purchased"},"tipSource":{"type":["string","null"],"enum":["chat","post","media_link"],"description":"For TIP messages, where the tip originated: 'chat' (direct in-chat tip), 'post' (tipped a feed post) or 'media_link' (tipped via a shared media link). Null for non-tip messages."},"sentByUserId":{"type":["string","null"],"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"},"appUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the third-party app that created this message through the public API. Null when the message was sent from the Fanvue dashboard, and for every message sent before app attribution was recorded."},"isRead":{"type":"boolean","description":"Whether the message has been read by the recipient"}},"required":["uuid","text","sentAt","sender","recipient","hasMedia","mediaType","mediaUuids","mediaPreviewUuid","gif","type","pricing","purchasedAt","tipSource","sentByUserId","appUuid","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":[],"mediaPreviewUuid":null,"gif":null,"pricing":null,"purchasedAt":null,"tipSource":null,"sentByUserId":null,"appUuid":"f6a7b8c9-0123-4567-89ab-cdef01234567","isRead":true},{"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"],"mediaPreviewUuid":"c3d4e5f6-a7b8-9012-cdef-345678901234","gif":null,"pricing":{"USD":{"price":500}},"purchasedAt":"2024-01-15T00:00:00.000Z","tipSource":null,"sentByUserId":null,"appUuid":null,"isRead":true},{"uuid":"c3d4e5f6-7890-1234-5678-9abcdef01234","text":"Thanks for the tip! 💖","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":"TIP","hasMedia":false,"mediaType":null,"mediaUuids":[],"mediaPreviewUuid":null,"gif":null,"pricing":{"USD":{"price":1000}},"purchasedAt":null,"tipSource":"post","sentByUserId":null,"appUuid":null,"isRead":true},{"uuid":"d4e5f6a7-8901-2345-6789-abcdef012345","text":"Check out my new exclusive content 🔥","sentAt":"2024-01-14T00: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":{},"type":"BROADCAST","hasMedia":true,"mediaType":"image","mediaUuids":["b2c3d4e5-f6a7-8901-bcde-f12345678901"],"mediaPreviewUuid":null,"gif":null,"pricing":null,"purchasedAt":null,"tipSource":null,"sentByUserId":null,"appUuid":null,"isRead":false},{"uuid":"e5f6a7b8-9012-3456-789a-bcdef0123456","text":null,"sentAt":"2024-01-14T00: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":false,"mediaType":null,"mediaUuids":[],"mediaPreviewUuid":null,"gif":{"id":"excited-happy-dance-xY7bQ","format":"WEBP","title":"excited happy dance","url":"https://cdn.klipy.com/excited-happy-dance-xY7bQ/md.webp","width":480,"height":360},"pricing":null,"purchasedAt":null,"tipSource":null,"sentByUserId":null,"appUuid":null,"isRead":false}],"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}/messages/{messageUuid}":{"get":{"summary":"Get a single message","description":"Returns a single message from a chat conversation with the specified user, by message UUID.\n\nThis is the single-message counterpart to `GET /chats/{userUuid}/messages` and returns the same message shape for one message, so you can reuse the same parsing.","operationId":"getMessage","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"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"responses":{"200":{"description":"Message details","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"text":{"type":["string","null"]},"sentAt":{"type":["string","null"],"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","null"]},"mediaType":{"type":["string","null"],"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)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the media item shown for free as a preview of this pay-to-view message, or null when no free preview was configured. Mirrors the `mediaPreviewUuid` set when sending the message."},"gif":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The GIF provider's durable identifier for this GIF. Stable across renditions; use it to de-duplicate or re-resolve the GIF."},"format":{"type":"string","enum":["GIF","WEBP","MP4","WEBM"],"description":"Encoding of the asset at `url`. Only `GIF` and `WEBP` are produced today, and both render in a plain <img> tag."},"title":{"type":["string","null"],"description":"Human-readable GIF title, suitable as alt text."},"url":{"type":["string","null"],"description":"Hotlink URL of the GIF, served from the provider's CDN — Fanvue does not host or proxy the asset. Null when the URL is temporarily withheld; the message is still a GIF message, so render a placeholder at `width`/`height` rather than treating it as empty."},"width":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic width of the asset at `url`, in pixels"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic height of the asset at `url`, in pixels"}},"required":["id","format","title","url","width","height"],"description":"The third-party GIF attached to this message, or null for an ordinary message. A GIF message carries no media and no price, but `text` may be set — a GIF can be sent with a caption."},"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"]},"pricing":{"type":["object","null"],"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","null"],"format":"date","description":"Timestamp when this message was purchased, or null if not purchased"},"tipSource":{"type":["string","null"],"enum":["chat","post","media_link"],"description":"For TIP messages, where the tip originated: 'chat' (direct in-chat tip), 'post' (tipped a feed post) or 'media_link' (tipped via a shared media link). Null for non-tip messages."},"sentByUserId":{"type":["string","null"],"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"},"appUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the third-party app that created this message through the public API. Null when the message was sent from the Fanvue dashboard, and for every message sent before app attribution was recorded."},"isRead":{"type":"boolean","description":"Whether the message has been read by the recipient"}},"required":["uuid","text","sentAt","sender","recipient","hasMedia","mediaType","mediaUuids","mediaPreviewUuid","gif","type","pricing","purchasedAt","tipSource","sentByUserId","appUuid","isRead"]},"example":{"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":[],"gif":null,"pricing":null,"purchasedAt":null,"tipSource":null,"sentByUserId":null,"appUuid":"f6a7b8c9-0123-4567-89ab-cdef01234567","isRead":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 message found with the given UUID in this conversation","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 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.","operationId":"deleteMessage","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"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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/{userUuid}":{"patch":{"summary":"Update chat properties","description":"Update properties of a chat conversation with a user, such as read status, mute status, or nickname.","operationId":"updateChat","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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"}}},"get":{"summary":"Get a single chat","description":"Returns the details of a single chat conversation between the authenticated user and the specified user, including read state, last message metadata, mute status, and unread message count.\n\nThis is the single-conversation counterpart to `GET /chats` and returns the same per-conversation shape for one chat.","operationId":"getChat","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userUuid","in":"path"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"responses":{"200":{"description":"Chat conversation details","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date"},"lastMessageAt":{"type":["string","null"],"format":"date","description":"Date of the last message in this chat"},"isRead":{"type":"boolean","description":"Whether the chat is read. Authoritative for unread badges: it is false either when unread messages exist or when the chat was manually marked unread via PATCH /chats/{userUuid}, in which case `unreadMessagesCount` stays 0."},"isMuted":{"type":"boolean"},"unreadMessagesCount":{"type":"number","description":"Number of messages in this chat the authenticated user has not read. 0 for a chat that was manually marked unread — use `isRead` for badge state."},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"lastMessage":{"type":["object","null"],"properties":{"text":{"type":["string","null"]},"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","null"],"format":"date"},"hasMedia":{"type":["boolean","null"]},"hasGif":{"type":"boolean","description":"Whether the last message is a GIF message. Its text may still be set as a caption. Fetch the message to get the GIF itself."},"mediaType":{"type":["string","null"],"enum":["image","video","audio","document"]},"senderUuid":{"type":"string","format":"uuid"},"senderRole":{"type":"string","enum":["FAN","CREATOR","AGENCY","SYSTEM"],"description":"Who sent the last message: CREATOR (the creator, sent directly), AGENCY (a team member sent it on the creator's behalf), FAN (the counterpart fan) or SYSTEM (an automated/platform message such as a subscription automation or KYC prompt)."},"sentByUserId":{"type":["string","null"],"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"},"status":{"type":["string","null"],"enum":["Sent","Delivered","Read"],"description":"Delivery status of the last message from the sender's perspective: Sent (still in flight), Delivered (sent but not yet read by the recipient) or Read. Null when the last message was received by the authenticated user (inbound)."}},"required":["text","type","uuid","sentAt","hasMedia","hasGif","mediaType","senderUuid","senderRole","sentByUserId"]},"isCreator":{"type":"boolean","description":"Whether the chat counterpart is also a creator on the platform"},"online":{"type":"boolean","description":"Whether the counterpart is currently online. Provided inline to avoid a separate /chats/statuses request."},"lastSeenAt":{"type":["string","null"],"format":"date","description":"When the counterpart was last seen online, or null if unknown/hidden"},"customLists":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Custom list UUID"},"name":{"type":"string","description":"Custom list name"}},"required":["uuid","name"]},"description":"Custom lists owned by the authenticated user that the counterpart belongs to"}},"required":["createdAt","lastMessageAt","isRead","isMuted","unreadMessagesCount","user","lastMessage"]},"example":{"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,"hasGif":false,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","senderRole":"CREATOR","sentByUserId":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":{"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/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.","operationId":"sendMassMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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"}},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of a single media item shown for free as a preview of a pay-to-view mass message. Requires a price and attached media."},"price":{"type":["number","null"],"minimum":300},"includedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Smart list identifiers — fixed string types such as 'subscribers' or 'followers', not UUIDs. The deprecated alias `smartListUuids` is also accepted."},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"excludedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Smart list identifiers — fixed string types such as 'subscribers' or 'followers', not UUIDs. The deprecated alias `smartListUuids` is also accepted."},"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":{"uuid":{"type":"string","format":"uuid","description":"UUID of the created mass message"},"publishedAt":{"type":["string","null"],"format":"date","description":"When the message was sent, or null when it is scheduled for later"},"recipientCount":{"type":"number","description":"Recipients resolved from the given lists at the time of this request. A scheduled message re-resolves its recipients at send time, so this is a preview and GET /chats/mass-messages reports 0 until it sends."}},"required":["uuid","publishedAt","recipientCount"]},"example":{"uuid":"f1e2d3c4-b5a6-9788-c0d1-e2f3a4b5c6d7","publishedAt":"2024-01-15T00:00:00.000Z","recipientCount":1250}}}},"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<Warning>This endpoint is only available to creators.</Warning>","operationId":"listMassMessages","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"]},"status":{"type":"string","enum":["SENT","UNSENT","SENDING","FAILED","MODERATED","SCHEDULED"],"description":"Current status of the mass message"},"price":{"type":["number","null"],"description":"Price in cents for pay-to-view content, or null if free"},"createdAt":{"type":["string","null"],"format":"date"},"publishedAt":{"type":["string","null"],"format":"date","description":"When the message was published/sent"},"scheduledAt":{"type":["string","null"],"format":"date","description":"When the message is scheduled to send, or null for non-scheduled messages"},"recipientCount":{"type":"number","description":"Number of recipients the message was sent to. 0 while the message is SCHEDULED — recipients are resolved at send time, so this only becomes final once the status leaves SCHEDULED."},"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)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ordered list of media UUIDs attached to this mass message (display order)"},"includedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]}},"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Deprecated alias of `smartListIds`. Will be removed in a future API version."},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["smartListIds","smartListUuids","customListUuids"],"description":"Smart and custom lists the mass message was sent to. Inner arrays are empty when none were used."},"excludedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]}},"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Deprecated alias of `smartListIds`. Will be removed in a future API version."},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["smartListIds","smartListUuids","customListUuids"],"description":"Smart and custom lists excluded from the mass message. Inner arrays are empty when none were used."}},"required":["uuid","text","status","price","createdAt","publishedAt","scheduledAt","recipientCount","viewCount","purchaseCount","totalRevenue","mediaUuids","includedLists","excludedLists"]},"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","scheduledAt":null,"recipientCount":1250,"viewCount":890,"purchaseCount":156,"totalRevenue":78000,"mediaUuids":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"includedLists":{"smartListIds":["subscribers","auto_renewing"],"smartListUuids":["subscribers","auto_renewing"],"customListUuids":["f1e2d3c4-b5a6-9788-c0d1-e2f3a4b5c6d7"]},"excludedLists":{"smartListIds":[],"smartListUuids":[],"customListUuids":[]}},{"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","scheduledAt":null,"recipientCount":1180,"viewCount":720,"purchaseCount":0,"totalRevenue":0,"mediaUuids":[],"includedLists":{"smartListIds":["followers"],"smartListUuids":["followers"],"customListUuids":[]},"excludedLists":{"smartListIds":["muted"],"smartListUuids":["muted"],"customListUuids":[]}}],"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.","operationId":"deleteMassMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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.","operationId":"updateMassMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"messageUuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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","null"],"minimum":300},"includedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Smart list identifiers — fixed string types such as 'subscribers' or 'followers', not UUIDs. The deprecated alias `smartListUuids` is also accepted."},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"excludedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Smart list identifiers — fixed string types such as 'subscribers' or 'followers', not UUIDs. The deprecated alias `smartListUuids` is also accepted."},"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/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>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `message.received`, `message.read` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/messages).\n</Info>","operationId":"getUnreadChatsCount","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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<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","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"],"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/messages/batch":{"post":{"summary":"Get messages from multiple chats in bulk","description":"Returns the most recent messages for up to 50 chats in a single request, keyed by the input chat UUID (the counterpart user UUID).\n\nThis is the bulk counterpart to `GET /chats/{userUuid}/messages`. It collapses N per-chat round trips into one POST and is intended for initial-sync flows and incremental refreshes.\n\nPer-key errors are reported inside the 200 response body so a single unreachable chat never collapses the whole request — consumers keep the rest and only retry the failing keys.\n\n**Modes:**\n- **Default**: returns the latest `limit` messages per chat, newest first. `hasMore` indicates older messages exist.\n- **Incremental (`sinceMessageUuid`)**: returns messages strictly published after the cursor message's publish date, newest first.\n\n**Out of scope:** Backwards history pagination (a `before` cursor). Use `oldestMessageUuid` from the response as the anchor when that ships.\n\n<Note>Maximum 50 chat UUIDs per request. Failed keys are reported as `{ \"error\": \"not_found\" }` — this covers both chats that don't exist and chats the caller isn't part of.</Note>\n\n<Note>Read-only: fetching messages in bulk does not mutate read state — messages are not marked read and `isRead` reflects each message's state at read time.</Note>","operationId":"messagesBatch","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chatUuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"description":"Array of chat UUIDs (counterpart user UUIDs) to fetch messages for (1-50)"},"sinceMessageUuid":{"type":"string","format":"uuid","description":"Optional cursor for incremental walks: returns only messages strictly after this message's publish date in each chat"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Maximum messages to return per chat (1-50, default: 20)"}},"required":["chatUuids"]}}}},"responses":{"200":{"description":"Per-chat messages or error for each requested chat. Always 200 when the request itself is valid, even if every key fails.","content":{"application/json":{"schema":{"type":"object","properties":{"byChat":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"text":{"type":["string","null"]},"sentAt":{"type":["string","null"],"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","null"]},"mediaType":{"type":["string","null"],"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)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the media item shown for free as a preview of this pay-to-view message, or null when no free preview was configured. Mirrors the `mediaPreviewUuid` set when sending the message."},"gif":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The GIF provider's durable identifier for this GIF. Stable across renditions; use it to de-duplicate or re-resolve the GIF."},"format":{"type":"string","enum":["GIF","WEBP","MP4","WEBM"],"description":"Encoding of the asset at `url`. Only `GIF` and `WEBP` are produced today, and both render in a plain <img> tag."},"title":{"type":["string","null"],"description":"Human-readable GIF title, suitable as alt text."},"url":{"type":["string","null"],"description":"Hotlink URL of the GIF, served from the provider's CDN — Fanvue does not host or proxy the asset. Null when the URL is temporarily withheld; the message is still a GIF message, so render a placeholder at `width`/`height` rather than treating it as empty."},"width":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic width of the asset at `url`, in pixels"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic height of the asset at `url`, in pixels"}},"required":["id","format","title","url","width","height"],"description":"The third-party GIF attached to this message, or null for an ordinary message. A GIF message carries no media and no price, but `text` may be set — a GIF can be sent with a caption."},"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"]},"pricing":{"type":["object","null"],"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","null"],"format":"date","description":"Timestamp when this message was purchased, or null if not purchased"},"tipSource":{"type":["string","null"],"enum":["chat","post","media_link"],"description":"For TIP messages, where the tip originated: 'chat' (direct in-chat tip), 'post' (tipped a feed post) or 'media_link' (tipped via a shared media link). Null for non-tip messages."},"sentByUserId":{"type":["string","null"],"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"},"appUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the third-party app that created this message through the public API. Null when the message was sent from the Fanvue dashboard, and for every message sent before app attribution was recorded."},"isRead":{"type":"boolean","description":"Whether the message has been read by the recipient"}},"required":["uuid","text","sentAt","sender","recipient","hasMedia","mediaType","mediaUuids","mediaPreviewUuid","gif","type","pricing","purchasedAt","tipSource","sentByUserId","appUuid","isRead"]}},"hasMore":{"type":"boolean","description":"Whether more messages exist beyond the returned set (older than `oldestMessageUuid` for the default newest-first read, or in the queried range for incremental walks)"},"oldestMessageUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the oldest message in the returned batch, or null if no messages were returned"}},"required":["messages","hasMore","oldestMessageUuid"]},{"type":"object","properties":{"error":{"type":"string","enum":["forbidden","not_found","internal"]}},"required":["error"]}]},"description":"Map of input chat UUID to messages or a per-key error"}},"required":["byChat"]},"example":{"byChat":{"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7":{"messages":[{"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":[],"mediaPreviewUuid":null,"gif":null,"pricing":null,"purchasedAt":null,"sentByUserId":null,"appUuid":"f6a7b8c9-0123-4567-89ab-cdef01234567","isRead":true}],"hasMore":true,"oldestMessageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"},"c3d4e5f6-7890-1234-5678-9abcdef01234":{"error":"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"}}}},"/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```","operationId":"listMedia","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"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"],"format":"date"},"sentAt":{"type":["string","null"],"format":"date"},"ownerUuid":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["variantType","displayPosition","width","height","lengthMs"]}},"purchasedAt":{"type":["string","null"],"format":"date","description":"Timestamp when the fan purchased the media's source message, or null if not purchased."},"pricing":{"type":["object","null"],"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Listed price of the media's source pay-to-view message, or null if free. This does not reflect discounts — see `amountPaid` for what the fan actually paid."},"amountPaid":{"type":["object","null"],"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Amount the fan actually paid to unlock the media's source message, after any discount. Null when not purchased (see `purchasedAt`) or free."}},"required":["uuid","messageUuid","mediaType","created_at","sentAt","ownerUuid","name"]}},"nextCursor":{"type":["string","null"],"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}],"purchasedAt":"2024-01-15T00:00:00.000Z","pricing":{"USD":{"price":1000}},"amountPaid":{"USD":{"price":700}}},{"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}],"purchasedAt":null,"pricing":null,"amountPaid":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<Note>The `mediaUuids` query parameter is required and accepts up to 20 UUIDs.</Note>","operationId":"getMessageMediaByUuids","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"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"responses":{"200":{"description":"Resolved media payload map","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"type":["object","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"messageUuid":{"type":"string","format":"uuid"},"mediaType":{"type":"string","enum":["image","video","audio","document","unknown"]},"created_at":{"type":["string","null"],"format":"date"},"sentAt":{"type":["string","null"],"format":"date"},"ownerUuid":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["variantType","displayPosition","width","height","lengthMs"]}},"purchasedAt":{"type":["string","null"],"format":"date","description":"Timestamp when the fan purchased the media's source message, or null if not purchased."},"pricing":{"type":["object","null"],"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Listed price of the media's source pay-to-view message, or null if free. This does not reflect discounts — see `amountPaid` for what the fan actually paid."},"amountPaid":{"type":["object","null"],"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Amount the fan actually paid to unlock the media's source message, after any discount. Null when not purchased (see `purchasedAt`) or free."}},"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}],"purchasedAt":"2024-01-15T00:00:00.000Z","pricing":{"USD":{"price":1000}},"amountPaid":{"USD":{"price":700}}},"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.","operationId":"getSmartLists","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","creators"],"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},{"name":"Creators","uuid":"creators","count":100}]}}},"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.","operationId":"getSmartListMembers","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","creators"],"description":"Smart list unique identifier"},"required":true,"description":"Smart list unique identifier","name":"uuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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.","operationId":"getCustomLists","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"],"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.","operationId":"createCustomList","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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","null"],"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.","operationId":"getCustomListMembers","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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.","operationId":"updateCustomList","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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.","operationId":"deleteCustomList","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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.","operationId":"addMembersToCustomList","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Custom list UUID"},"required":true,"description":"Custom list UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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.","operationId":"removeMemberFromCustomList","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"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"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.","operationId":"listTemplateMessages","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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"},"name":{"type":["string","null"],"description":"Template name as given on create, or null when the template is unnamed"},"text":{"type":["string","null"],"description":"Message text content"},"price":{"type":["number","null"],"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"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"Media UUID used as the paywall preview (null when the template has none)"},"folderUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the folder containing this template"},"folderName":{"type":["string","null"],"description":"Name of the folder containing this template"}},"required":["uuid","name","text","price","mediaUuids","mediaPreviewUuid","folderUuid","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","name":"Subscriber welcome","text":"Hey! Thanks for subscribing! Check out my latest exclusive content 🔥","price":999,"folderUuid":"b0a1c2d3-e4f5-6789-abcd-ef0123456789","folderName":"Welcome Messages","mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"mediaPreviewUuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8"},{"uuid":"123e4567-e89b-12d3-a456-426614174001","name":null,"text":"Happy Friday! Here's something special just for you 💝","price":null,"folderUuid":"c1b2a3d4-f5e6-7890-bcde-f01234567890","folderName":"Promotions","mediaUuids":[],"mediaPreviewUuid":null},{"uuid":"123e4567-e89b-12d3-a456-426614174002","name":"Friday promo","text":"Check out this exclusive content! Limited time offer 🎁","price":1499,"folderUuid":"c1b2a3d4-f5e6-7890-bcde-f01234567890","folderName":"Promotions","mediaUuids":["8d9e6679-7425-40de-944b-e07fc1f90ae8","9e9e6679-7425-40de-944b-e07fc1f90ae9"],"mediaPreviewUuid":null}],"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"}}},"post":{"summary":"Create or edit a template message","description":"Creates a template message in one of the creator's folders, or edits an existing one. Provide a `folderUuid` from GET /chats/templates/folders. Omit `messageUuid` to create the template (201); provide it to edit that template in place (200). A template must have text or at least one media attachment. An edit replaces the fields you send, so send the full template body rather than only the fields you are changing.","operationId":"upsertTemplateMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messageUuid":{"type":"string","format":"uuid","description":"UUID of an existing template to edit. Omit to create a new template; provide it to edit that template in place."},"folderUuid":{"type":"string","format":"uuid","description":"UUID of the folder to hold the template (see GET /chats/templates/folders)"},"text":{"type":"string","description":"Message text content"},"price":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","minimum":300,"maximum":250000},{"type":"null"}],"description":"Message price in cents (0 or null for free messages)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Media UUIDs to attach to the template, in display order"},"mediaPreviewUuid":{"type":"string","format":"uuid","description":"Media UUID to use as the paywall preview"},"name":{"type":"string","description":"Optional template name"}},"required":["folderUuid"]}}}},"responses":{"200":{"description":"Template message updated","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Template message UUID"},"name":{"type":["string","null"],"description":"Template name as given on create, or null when the template is unnamed"},"text":{"type":["string","null"],"description":"Message text content"},"price":{"type":["number","null"],"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"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"Media UUID used as the paywall preview (null when the template has none)"},"folderUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the folder containing this template"},"folderName":{"type":["string","null"],"description":"Name of the folder containing this template"}},"required":["uuid","name","text","price","mediaUuids","mediaPreviewUuid","folderUuid","folderName"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174003","name":"Welcome gift","text":"Welcome! Here's a little something to say thanks 💖","price":500,"folderUuid":"b0a1c2d3-e4f5-6789-abcd-ef0123456789","folderName":"Welcome Messages","mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"mediaPreviewUuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8"}}}},"201":{"description":"Template message created","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Template message UUID"},"name":{"type":["string","null"],"description":"Template name as given on create, or null when the template is unnamed"},"text":{"type":["string","null"],"description":"Message text content"},"price":{"type":["number","null"],"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"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"Media UUID used as the paywall preview (null when the template has none)"},"folderUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the folder containing this template"},"folderName":{"type":["string","null"],"description":"Name of the folder containing this template"}},"required":["uuid","name","text","price","mediaUuids","mediaPreviewUuid","folderUuid","folderName"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174003","name":"Welcome gift","text":"Welcome! Here's a little something to say thanks 💖","price":500,"folderUuid":"b0a1c2d3-e4f5-6789-abcd-ef0123456789","folderName":"Welcome Messages","mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"mediaPreviewUuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8"}}}},"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":{"description":"Folder or 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"}}}},"/chats/templates/folders":{"get":{"summary":"Get list of template folders","description":"Returns a paginated list of the creator's template folders. Use a folder UUID when creating a template with POST /chats/templates.","operationId":"listTemplateFolders","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"responses":{"200":{"description":"List of template folders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Template folder UUID"},"name":{"type":"string","description":"Template folder name"}},"required":["uuid","name"]},"description":"Array of template 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":[{"uuid":"b0a1c2d3-e4f5-6789-abcd-ef0123456789","name":"Welcome Messages"},{"uuid":"c1b2a3d4-f5e6-7890-bcde-f01234567890","name":"Promotions"}],"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 template folder","description":"Creates a template folder for the creator. Use the returned `uuid` as `folderUuid` when creating templates with POST /chats/templates.","operationId":"createTemplateFolder","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Template folder name"}},"required":["name"]}}}},"responses":{"201":{"description":"Template folder created","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Template folder UUID"},"name":{"type":"string","description":"Template folder name"}},"required":["uuid","name"]},"example":{"uuid":"b0a1c2d3-e4f5-6789-abcd-ef0123456789","name":"Welcome Messages"}}}},"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 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"}}}},"/chats/templates/folders/{folderUuid}":{"patch":{"summary":"Rename a template folder","description":"Renames one of the creator's template folders.","operationId":"updateTemplateFolder","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Template folder UUID"},"required":true,"description":"Template folder UUID","name":"folderUuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Template folder name"}},"required":["name"]}}}},"responses":{"200":{"description":"Template folder renamed","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Template folder UUID"},"name":{"type":"string","description":"Template folder name"}},"required":["uuid","name"]},"example":{"uuid":"b0a1c2d3-e4f5-6789-abcd-ef0123456789","name":"Welcome Messages"}}}},"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 folder not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"A 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"}}}},"/chats/templates/{templateUuid}":{"get":{"summary":"Get a single template message","description":"Returns a specific template message by UUID.","operationId":"getTemplateMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Template message UUID"},"required":true,"description":"Template message UUID","name":"templateUuid","in":"path"}],"security":[{"BearerAuth":["read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"responses":{"200":{"description":"Template message details","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Template message UUID"},"name":{"type":["string","null"],"description":"Template name as given on create, or null when the template is unnamed"},"text":{"type":["string","null"],"description":"Message text content"},"price":{"type":["number","null"],"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"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"Media UUID used as the paywall preview (null when the template has none)"},"folderUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the folder containing this template"},"folderName":{"type":["string","null"],"description":"Name of the folder containing this template"}},"required":["uuid","name","text","price","mediaUuids","mediaPreviewUuid","folderUuid","folderName"]},"example":{"uuid":"123e4567-e89b-12d3-a456-426614174000","name":"Subscriber welcome","text":"Hey! Thanks for subscribing! Check out my latest exclusive content 🔥","price":999,"folderUuid":"b0a1c2d3-e4f5-6789-abcd-ef0123456789","folderName":"Welcome Messages","mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"mediaPreviewUuid":"6ba7b810-9dad-11d1-80b4-00c04fd430c8"}}}},"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"}}},"delete":{"summary":"Delete a template message","description":"Deletes a template message by UUID.","operationId":"deleteTemplateMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Template message UUID"},"required":true,"description":"Template message UUID","name":"templateUuid","in":"path"}],"security":[{"BearerAuth":["write:chat"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n</Info>"},"responses":{"204":{"description":"Template message deleted"},"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"}}}},"/chats/automated-messages":{"get":{"summary":"List automated messages","description":"Returns the per-trigger state of the authenticated creator's automated messages. All triggers are always listed; disabled triggers have `enabled: false` and null content fields.","operationId":"listAutomatedMessages","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Per-trigger automated message state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"trigger":{"type":"string","enum":["new_subscriber","new_follower","subscription_canceled","re_subscribed","renewed","new_purchase","first_message_reply"],"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)"},"enabled":{"type":"boolean","description":"Whether an automated message is active for this trigger"},"text":{"type":["string","null"],"description":"Message text content (null when disabled or media-only)"},"price":{"type":["number","null"],"description":"Pay-to-view price in cents (null when disabled or unpriced)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ordered list of media UUIDs attached to the message (empty when disabled)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the free preview media, or null when none is set"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the automated message was last configured (null when disabled)"}},"required":["trigger","enabled","text","price","mediaUuids","mediaPreviewUuid","updatedAt"]},"description":"Per-trigger state for all automated message triggers"}},"required":["data"]},"example":{"data":[{"trigger":"new_subscriber","enabled":true,"text":"Hey! Thanks for subscribing! Check out my latest exclusive content 🔥","price":999,"mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"mediaPreviewUuid":"8d9e6679-7425-40de-944b-e07fc1f90ae8","updatedAt":"2026-07-01T12:00:00.000Z"},{"trigger":"new_follower","enabled":true,"text":"Thanks for the follow! 💝","price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":"2026-06-15T09:30:00.000Z"},{"trigger":"subscription_canceled","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":null},{"trigger":"re_subscribed","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":null},{"trigger":"renewed","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":null},{"trigger":"new_purchase","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":null},{"trigger":"first_message_reply","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":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/automated-messages/{trigger}":{"put":{"summary":"Enable or update an automated message","description":"Creates or replaces the automated message sent when the trigger fires. The message must have text or media; a non-zero price requires media.","operationId":"upsertAutomatedMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","enum":["new_subscriber","new_follower","subscription_canceled","re_subscribed","renewed","new_purchase","first_message_reply"],"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)"},"required":true,"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)","name":"trigger","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":5000,"description":"Message text content"},"price":{"anyOf":[{"type":"number","enum":[0]},{"type":"integer","minimum":300,"maximum":250000}],"description":"Pay-to-view price in cents: 0 (free) or between 300 and 250000. A non-zero price requires attached media."},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs to attach to the message"},"mediaPreviewUuid":{"type":"string","format":"uuid","description":"UUID of a single media item shown for free as a preview of a pay-to-view message. Requires a price and attached media."}}}}}},"responses":{"200":{"description":"Automated message enabled or updated","content":{"application/json":{"schema":{"type":"object","properties":{"trigger":{"type":"string","enum":["new_subscriber","new_follower","subscription_canceled","re_subscribed","renewed","new_purchase","first_message_reply"],"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)"},"enabled":{"type":"boolean","description":"Whether an automated message is active for this trigger"},"text":{"type":["string","null"],"description":"Message text content (null when disabled or media-only)"},"price":{"type":["number","null"],"description":"Pay-to-view price in cents (null when disabled or unpriced)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ordered list of media UUIDs attached to the message (empty when disabled)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the free preview media, or null when none is set"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the automated message was last configured (null when disabled)"}},"required":["trigger","enabled","text","price","mediaUuids","mediaPreviewUuid","updatedAt"]},"example":{"trigger":"new_subscriber","enabled":true,"text":"Hey! Thanks for subscribing! Check out my latest exclusive content 🔥","price":999,"mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"mediaPreviewUuid":"8d9e6679-7425-40de-944b-e07fc1f90ae8","updatedAt":"2026-07-01T12:00:00.000Z"}}}},"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"}}},"delete":{"summary":"Disable an automated message","description":"Disables the automated message for the trigger. Returns 404 if the trigger is not currently enabled.","operationId":"deleteAutomatedMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","enum":["new_subscriber","new_follower","subscription_canceled","re_subscribed","renewed","new_purchase","first_message_reply"],"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)"},"required":true,"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)","name":"trigger","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Automated message disabled"},"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":{"description":"Automated 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"}}}},"/checkout-links":{"get":{"summary":"List checkout links","description":"List the authenticated creator's checkout links, newest first. Soft-deleted links are excluded; disabled links are included with `status: disabled`. All amounts are integer minor units of the currency (e.g. cents).","operationId":"listCheckoutLinks","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of checkout links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Checkout link UUID"},"name":{"type":"string","description":"Creator-internal label for the link (derived from the product name)"},"description":{"type":["string","null"],"description":"Creator-internal note (null when unset). Fans never see it."},"url":{"type":["string","null"],"description":"Shareable checkout URL fans use to purchase"},"price":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents). 0 for free links."},"currency":{"type":"string","description":"ISO-4217 currency code of the price"},"isRecurring":{"type":"boolean","description":"Whether purchases create a recurring subscription"},"cycleLength":{"type":["integer","null"],"description":"Billing cycle length (null for one-off prices)"},"cycleUnit":{"type":["string","null"],"enum":["day","week","month","year"],"description":"Billing cycle unit (null for one-off prices)"},"productUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the product the link sells"},"productPriceUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the product price the link sells"},"status":{"type":"string","enum":["active","disabled"],"description":"active links can be purchased; disabled links reject checkout until re-enabled"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","name","description","url","price","currency","isRecurring","cycleLength","cycleUnit","productUuid","productPriceUuid","status","createdAt"]},"description":"The creator's checkout links, newest first"},"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":"b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e","name":"Coaching call","description":"Instagram bio link","url":"https://www.fanvue.com/checkout/fvcl_4WqZz1kXo9DdPp2sT7yRfM","price":1999,"currency":"USD","isRecurring":false,"cycleLength":null,"cycleUnit":null,"productUuid":"c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f","productPriceUuid":"d5e6f7a8-9b0c-4d1e-af2a-3b4c5d6e7f8a","status":"active","createdAt":"2024-01-15T00:00:00.000Z"},{"uuid":"e6f7a8b9-0c1d-4e2f-ba3b-4c5d6e7f8a9b","name":"Monthly membership","description":null,"url":"https://www.fanvue.com/checkout/fvcl_9XrYy2lWn8CcOq3tU6zSgN","price":2500,"currency":"USD","isRecurring":true,"cycleLength":1,"cycleUnit":"month","productUuid":"f7a8b9c0-1d2e-4f3a-8b4c-5d6e7f8a9b0c","productPriceUuid":"a8b9c0d1-2e3f-4a4b-9c5d-6e7f8a9b0c1d","status":"disabled","createdAt":"2024-01-14T00:00:00.000Z"}],"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"}}},"post":{"summary":"Create a checkout link","description":"Create a shareable checkout link selling either an existing product price (`existing_price`), a new price on an existing product (`existing_product`), or a brand-new product (`new_product`).\n\nAll amounts are integer minor units of the currency (e.g. cents: 1999 = $19.99); the Fanvue dashboard displays the same prices in major units. Requires checkout links to be enabled for the creator.","operationId":"createCheckoutLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","maxLength":500,"description":"Internal note shown only in the creator dashboard. Fans never see it."},"redirectUrl":{"type":"string","format":"uri","description":"URL fans are redirected to after a successful purchase."},"source":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["existing_price"],"description":"Sell an existing product price through the new link."},"productPriceUuid":{"type":"string","format":"uuid","description":"UUID of the existing product price to sell."}},"required":["kind","productPriceUuid"]},{"type":"object","properties":{"kind":{"type":"string","enum":["existing_product"],"description":"Mint a new price on an existing product and sell it through the new link."},"productUuid":{"type":"string","format":"uuid","description":"UUID of the existing product to price."},"price":{"type":"object","properties":{"amount":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents: 1999 = $19.99). 0 creates a free link; paid links must be between 300 and 1000000 minor units ($3-$10,000). Note: the Fanvue dashboard displays prices in major units; this API always uses integer minor units."},"currency":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"USD","description":"3-letter uppercase ISO-4217 currency code. Defaults to USD."},"isRecurring":{"type":"boolean","description":"Whether purchases bill on a recurring cycle (subscription) or once. Recurring prices require a non-zero amount plus cycleLength and cycleUnit."},"cycleLength":{"type":"integer","exclusiveMinimum":0,"description":"Billing cycle length. Required (with cycleUnit) when isRecurring is true."},"cycleUnit":{"type":"string","enum":["day","week","month","year"],"description":"Billing cycle unit. Required (with cycleLength) when isRecurring is true."}},"required":["amount","isRecurring"]}},"required":["kind","productUuid","price"]},{"type":"object","properties":{"kind":{"type":"string","enum":["new_product"],"description":"Create a brand-new product with a price and sell it through the new link."},"product":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Product name. Must be unique (case-insensitive) among the creator's products."},"description":{"type":"string","maxLength":500,"description":"Optional product description."}},"required":["name"]},"price":{"type":"object","properties":{"amount":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents: 1999 = $19.99). 0 creates a free link; paid links must be between 300 and 1000000 minor units ($3-$10,000). Note: the Fanvue dashboard displays prices in major units; this API always uses integer minor units."},"currency":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"USD","description":"3-letter uppercase ISO-4217 currency code. Defaults to USD."},"isRecurring":{"type":"boolean","description":"Whether purchases bill on a recurring cycle (subscription) or once. Recurring prices require a non-zero amount plus cycleLength and cycleUnit."},"cycleLength":{"type":"integer","exclusiveMinimum":0,"description":"Billing cycle length. Required (with cycleUnit) when isRecurring is true."},"cycleUnit":{"type":"string","enum":["day","week","month","year"],"description":"Billing cycle unit. Required (with cycleLength) when isRecurring is true."}},"required":["amount","isRecurring"]}},"required":["kind","product","price"]}],"description":"What the link sells: an existing price (`existing_price`), a new price on an existing product (`existing_product`), or a brand-new product (`new_product`)."}},"required":["source"]}}}},"responses":{"201":{"description":"Checkout link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Checkout link UUID"},"name":{"type":"string","description":"Creator-internal label for the link (derived from the product name)"},"description":{"type":["string","null"],"description":"Creator-internal note (null when unset). Fans never see it."},"url":{"type":["string","null"],"description":"Shareable checkout URL fans use to purchase"},"price":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents). 0 for free links."},"currency":{"type":"string","description":"ISO-4217 currency code of the price"},"isRecurring":{"type":"boolean","description":"Whether purchases create a recurring subscription"},"cycleLength":{"type":["integer","null"],"description":"Billing cycle length (null for one-off prices)"},"cycleUnit":{"type":["string","null"],"enum":["day","week","month","year"],"description":"Billing cycle unit (null for one-off prices)"},"productUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the product the link sells"},"productPriceUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the product price the link sells"},"status":{"type":"string","enum":["active","disabled"],"description":"active links can be purchased; disabled links reject checkout until re-enabled"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","name","description","url","price","currency","isRecurring","cycleLength","cycleUnit","productUuid","productPriceUuid","status","createdAt"]},"example":{"uuid":"b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e","name":"Coaching call","description":"Instagram bio link","url":"https://www.fanvue.com/checkout/fvcl_4WqZz1kXo9DdPp2sT7yRfM","price":1999,"currency":"USD","isRecurring":false,"cycleLength":null,"cycleUnit":null,"productUuid":"c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f","productPriceUuid":"d5e6f7a8-9b0c-4d1e-af2a-3b4c5d6e7f8a","status":"active","createdAt":"2024-01-15T00:00:00.000Z"}}}},"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"}}}},"/checkout-links/{uuid}":{"patch":{"summary":"Enable or disable a checkout link","description":"Toggle a checkout link's status. Disabling is reversible: the link's checkout page stops accepting purchases until it is set back to active. Deleted links cannot be re-enabled.","operationId":"updateCheckoutLinkStatus","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Checkout link UUID"},"required":true,"description":"Checkout link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","disabled"],"description":"Set to disabled to stop the link's checkout page (reversible), or active to re-enable it."}},"required":["status"]}}}},"responses":{"200":{"description":"Checkout link status updated","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Checkout link UUID"},"status":{"type":"string","enum":["active","disabled"],"description":"active links can be purchased; disabled links reject checkout until re-enabled"}},"required":["uuid","status"]},"example":{"uuid":"b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e","status":"disabled"}}}},"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 checkout link","description":"Soft-delete a checkout link so it can no longer be purchased or re-enabled. Deletion is terminal; past payments remain available on the payments endpoints.","operationId":"deleteCheckoutLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Checkout link UUID"},"required":true,"description":"Checkout link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Checkout 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"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/collections":{"post":{"summary":"Create a content collection","description":"Create a new content collection for the authenticated creator.","operationId":"createCollection","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100,"description":"Label for the new collection"}},"required":["label"]}}}},"responses":{"201":{"description":"Collection created","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display label of the collection"},"createdAt":{"type":["string","null"],"format":"date","description":"When the collection was created"}},"required":["uuid","label","createdAt"]},"example":{"uuid":"550e8400-e29b-41d4-a716-446655440000","label":"Behind the scenes","createdAt":"2025-01-15T10:30:00.000Z"}}}},"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 collection with this label already exists","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"},"503":{"description":"Upstream collections service is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"get":{"summary":"List content collections","description":"Returns a paginated list of the authenticated creator's content collections.","operationId":"listCollections","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n</Info>"},"responses":{"200":{"description":"List of collections","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Unique identifier of the collection"},"label":{"type":"string","description":"Display label of the collection"},"createdAt":{"type":["string","null"],"format":"date","description":"When the collection was created"}},"required":["uuid","label","createdAt"]},"description":"Array of collections"},"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","label":"Behind the scenes","createdAt":"2025-01-15T10:30:00.000Z"},{"uuid":"550e8400-e29b-41d4-a716-446655440001","label":"Promos","createdAt":"2025-01-16T14:20:00.000Z"}],"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"},"503":{"description":"Upstream collections service is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/collections/{uuid}":{"patch":{"summary":"Rename a content collection","description":"Rename an existing content collection owned by the authenticated creator.","operationId":"renameCollection","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100,"description":"New label for the collection"}},"required":["label"]}}}},"responses":{"204":{"description":"Collection 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":"A collection with this label already exists","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"},"503":{"description":"Upstream collections service is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"delete":{"summary":"Delete a content collection","description":"Delete a content collection owned by the authenticated creator.\nPosts assigned to the collection remain; only the collection association is removed.","operationId":"deleteCollection","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"responses":{"204":{"description":"Collection 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"},"503":{"description":"Upstream collections service is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/creators":{"get":{"summary":"Get agency creators","description":"Returns a paginated list of creators associated with the authenticated agency user's organization.\n\nReturns 403 when the authenticated account holds no agency team-member seat, so an empty list always means the agency has no creators rather than the token not being an agency one.","operationId":"listCreators","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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.","operationId":"listCreatorFollowers","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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}/account":{"get":{"summary":"Get account view for a managed creator","description":"Get the account view (profile, status, earnings totals, last payout, fan counts) for a creator the authenticated agency team member manages.","operationId":"getCreatorAccount","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Account details for the managed creator","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"handle":{"type":"string"},"displayName":{"type":"string"},"isCreator":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"avatarUrl":{"type":["string","null"]},"bannerUrl":{"type":["string","null"]},"bio":{"type":"string"},"account":{"type":"object","properties":{"status":{"type":"string","enum":["active","suspended"],"description":"Account lifecycle status"},"subscriptionPrice":{"type":["integer","null"],"description":"Current monthly subscription price in USD cents (minor units), or null when no price is set (e.g. non-creator accounts). This is the creator's current setting, updatable via PATCH /users/me/subscription-price."},"earnings":{"type":"object","properties":{"total":{"type":"number","description":"All-time gross earnings (sum of paid earning invoices), in USD cents"},"availableBalance":{"type":"number","description":"Current available balance that can be withdrawn, in USD cents"},"lastPayoutAt":{"type":["string","null"],"format":"date-time","description":"Date of the most recent payout (paid_at), or null if there has been no payout"}},"required":["total","availableBalance","lastPayoutAt"]},"fans":{"type":"object","properties":{"followers":{"type":"number","description":"Number of contactable followers"},"subscribers":{"type":"number","description":"Number of contactable active subscribers"}},"required":["followers","subscribers"]}},"required":["status","subscriptionPrice","earnings","fans"]}},"required":["uuid","email","handle","displayName","isCreator","createdAt","updatedAt","avatarUrl","bannerUrl","bio","account"]},"example":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","email":"johnny@fanvue.com","handle":"johnny-doey","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","bio":"Content creator and influencer","account":{"status":"active","subscriptionPrice":999,"earnings":{"total":1532400,"availableBalance":412800,"lastPayoutAt":"2024-11-28T09:00:00.000Z"},"fans":{"followers":3420,"subscribers":890}}}}}},"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.","operationId":"listCreatorSubscribers","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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":"Opaque pagination cursor from a previous response's pagination.nextCursor. When provided, page is ignored; size applies when explicitly passed. Cursor pagination is more efficient than page-based pagination for iterating over large subscriber lists."},"required":false,"description":"Opaque pagination cursor from a previous response's pagination.nextCursor. When provided, page is ignored; size applies when explicitly passed. Cursor pagination is more efficient than page-based pagination for iterating over large subscriber lists.","name":"cursor","in":"query"}],"security":[{"BearerAuth":["read:creator","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"},"subscription":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["active","cancelled","pending_confirmation","paused"],"description":"Current status of the subscriber's subscription to this creator"},"price":{"type":"number","description":"Configured subscription price per period, in minor currency units (cents). This is the list price and does not reflect discounts or free trials — see `amountPaid` for the actual amount charged."},"amountPaid":{"type":"number","description":"Amount actually charged for the current period, in minor currency units (cents), after any discount. 0 when nothing has been charged yet (e.g. a fan inside a free trial)."},"currentPeriodStart":{"type":"string","format":"date-time","description":"Start of the current subscription period (ISO 8601)"},"currentPeriodEnd":{"type":["string","null"],"format":"date-time","description":"End of the current subscription period / next renewal date (ISO 8601), or null"},"autoRenewalEnabled":{"type":"boolean","description":"Whether the subscription is set to auto-renew (rebill) at the end of the period"}},"required":["status","price","amountPaid","currentPeriodStart","currentPeriodEnd","autoRenewalEnabled"],"description":"Details of the subscriber's current subscription to this creator, or null if none is found"},"firstSubscribedAt":{"type":["string","null"],"format":"date-time","description":"When the fan first subscribed to this creator (earliest across their whole subscription history), used to tell a genuinely new fan from a re-subscriber. Null if unknown."}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt","subscription","firstSubscribedAt"]},"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"},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page; pass it as the cursor query parameter. Null when there are no further results, or when sorting by name (cursor pagination is only supported for the subscribedAt sort)."}},"required":["page","size","hasMore","nextCursor"],"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","subscription":{"status":"active","price":999,"amountPaid":999,"currentPeriodStart":"2026-05-15T00:00:00.000Z","currentPeriodEnd":"2026-06-15T00:00:00.000Z","autoRenewalEnabled":true},"firstSubscribedAt":"2025-11-15T00:00:00.000Z"},{"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","subscription":{"status":"cancelled","price":1499,"amountPaid":1499,"currentPeriodStart":"2026-06-01T00:00:00.000Z","currentPeriodEnd":"2026-07-01T00:00:00.000Z","autoRenewalEnabled":false},"firstSubscribedAt":"2026-06-01T00:00:00.000Z"}],"pagination":{"page":1,"size":2,"hasMore":true,"nextCursor":"1lJx2vQ8pT4nBqM6Yr3wEuA9cKfHdG7iZsO0aXeUCnRLb5DkS8yWmVhP1oTgFj2N"}}}}},"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}/notifications":{"get":{"summary":"Get creator notifications feed","description":"Returns a paginated list of notifications received by the specified creator. Optionally filter by event type.","operationId":"listCreatorNotifications","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"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":"integer","description":"Filter notifications by event type id"},"required":false,"description":"Filter notifications by event type id","name":"eventType","in":"query"}],"security":[{"BearerAuth":["read:creator","read:self"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"200":{"description":"List of creator notifications","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"eventType":{"type":"integer","description":"Numeric event id (6=post comment, 7=post like, 9=purchase, 10=new subscriber, 11=tip, 12=new follower, 14=promotion, 19=creator promo payment, 26=account health, 27=poll closed, 28=fan churn risk)"},"isRead":{"type":"boolean"},"data":{"type":"object","additionalProperties":{},"description":"Event-specific payload. Shape varies by eventType."},"originator":{"type":["object","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"avatarUrl":{"type":["string","null"]},"isCreator":{"type":"boolean"}},"required":["uuid","handle","displayName","avatarUrl","isCreator"]},"receiverUuid":{"type":"string","format":"uuid","description":"UUID of the user who received the notification"}},"required":["uuid","createdAt","eventType","isRead","data","originator","receiverUuid"]},"description":"Array of notifications"},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null if none"}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"6c3d8b1c-9b1f-4b6e-8d77-4e8b22ff9a01","createdAt":"2026-05-22T08:30:00.000Z","eventType":11,"isRead":false,"data":{"price":500},"originator":{"uuid":"8a3a93e2-1c2a-4b6c-b4fd-1cdaaa6fbc11","handle":"sarahmiller","displayName":"Sarah Miller","avatarUrl":"https://media.fanvue.com/avatars/sarahmiller.jpg","isCreator":false},"receiverUuid":"2bde24e6-942b-49d4-b7b9-8d1e8eccbffb"},{"uuid":"f1d2e3b4-aaaa-4f5b-9c1d-2c2dffe11a23","createdAt":"2026-05-21T18:12:43.000Z","eventType":12,"isRead":true,"data":{},"originator":{"uuid":"21f5c1ab-7d22-4e7d-9c2b-e1c3a4f6bb22","handle":"mikejohnson","displayName":"Mike Johnson","avatarUrl":null,"isCreator":false},"receiverUuid":"2bde24e6-942b-49d4-b7b9-8d1e8eccbffb"}],"nextCursor":"eyJvZmZzZXQiOjIwfQ"}}}},"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.","operationId":"listCreatorChats","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"responses":{"200":{"description":"List of creator chats","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date"},"lastMessageAt":{"type":["string","null"],"format":"date","description":"Date of the last message in this chat"},"isRead":{"type":"boolean","description":"Whether the chat is read. Authoritative for unread badges: it is false either when unread messages exist or when the chat was manually marked unread via PATCH /chats/{userUuid}, in which case `unreadMessagesCount` stays 0."},"isMuted":{"type":"boolean"},"unreadMessagesCount":{"type":"number","description":"Number of messages in this chat the authenticated user has not read. 0 for a chat that was manually marked unread — use `isRead` for badge state."},"user":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},"lastMessage":{"type":["object","null"],"properties":{"text":{"type":["string","null"]},"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","null"],"format":"date"},"hasMedia":{"type":["boolean","null"]},"hasGif":{"type":"boolean","description":"Whether the last message is a GIF message. Its text may still be set as a caption. Fetch the message to get the GIF itself."},"mediaType":{"type":["string","null"],"enum":["image","video","audio","document"]},"senderUuid":{"type":"string","format":"uuid"},"senderRole":{"type":"string","enum":["FAN","CREATOR","AGENCY","SYSTEM"],"description":"Who sent the last message: CREATOR (the creator, sent directly), AGENCY (a team member sent it on the creator's behalf), FAN (the counterpart fan) or SYSTEM (an automated/platform message such as a subscription automation or KYC prompt)."},"sentByUserId":{"type":["string","null"],"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"},"status":{"type":["string","null"],"enum":["Sent","Delivered","Read"],"description":"Delivery status of the last message from the sender's perspective: Sent (still in flight), Delivered (sent but not yet read by the recipient) or Read. Null when the last message was received by the authenticated user (inbound)."}},"required":["text","type","uuid","sentAt","hasMedia","hasGif","mediaType","senderUuid","senderRole","sentByUserId"]},"isCreator":{"type":"boolean","description":"Whether the chat counterpart is also a creator on the platform"},"online":{"type":"boolean","description":"Whether the counterpart is currently online. Provided inline to avoid a separate /chats/statuses request."},"lastSeenAt":{"type":["string","null"],"format":"date","description":"When the counterpart was last seen online, or null if unknown/hidden"},"customLists":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Custom list UUID"},"name":{"type":"string","description":"Custom list name"}},"required":["uuid","name"]},"description":"Custom lists owned by the authenticated user that the counterpart belongs to"}},"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"},"isCreator":false,"online":true,"lastSeenAt":"2024-01-15T00:00:00.000Z","customLists":[{"uuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","name":"VIPs"}],"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,"hasGif":false,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","senderRole":"CREATOR","sentByUserId":null,"status":"Read"}},{"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,"hasGif":false,"mediaType":"image","senderUuid":"c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8","senderRole":"CREATOR","sentByUserId":null,"status":"Delivered"}}],"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.","operationId":"createCreatorChat","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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.","operationId":"sendCreatorMessage","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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":["string","null"],"minLength":1,"maxLength":5000},"gif":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The GIF provider's durable identifier for this GIF (as returned on a GIF message)"},"format":{"type":"string","enum":["GIF","WEBP"],"description":"Encoding of the asset at `url`"},"title":{"type":["string","null"],"description":"Human-readable GIF title, used as alt text. Accepts null as well as omission, so the `gif` block returned by a read can be sent back unchanged."},"url":{"type":"string","format":"uri","description":"Hotlink URL of the GIF on the provider's CDN"},"width":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic width of the asset at `url`, in pixels"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic height of the asset at `url`, in pixels"}},"required":["id","format","url","width","height"],"description":"A third-party GIF to send in place of media. May be sent on its own or alongside `text`, which is rendered as a caption. Cannot be combined with `mediaUuids`, `mediaPreviewUuid`, `price` or `templateUuid`."},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"}},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of a single media item shown for free as a preview of a pay-to-view message. Requires a price and attached media (or a template)."},"price":{"type":["number","null"],"minimum":300},"templateUuid":{"type":["string","null"],"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.","operationId":"sendCreatorMassMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:chat","read:creator","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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"}},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of a single media item shown for free as a preview of a pay-to-view mass message. Requires a price and attached media."},"price":{"type":["number","null"],"minimum":300},"includedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Smart list identifiers — fixed string types such as 'subscribers' or 'followers', not UUIDs. The deprecated alias `smartListUuids` is also accepted."},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"excludedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Smart list identifiers — fixed string types such as 'subscribers' or 'followers', not UUIDs. The deprecated alias `smartListUuids` is also accepted."},"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":{"uuid":{"type":"string","format":"uuid","description":"UUID of the created mass message"},"publishedAt":{"type":["string","null"],"format":"date","description":"When the message was sent, or null when it is scheduled for later"},"recipientCount":{"type":"number","description":"Recipients resolved from the given lists at the time of this request. A scheduled message re-resolves its recipients at send time, so this is a preview and GET /chats/mass-messages reports 0 until it sends."}},"required":["uuid","publishedAt","recipientCount"]},"example":{"uuid":"f1e2d3c4-b5a6-9788-c0d1-e2f3a4b5c6d7","publishedAt":"2024-01-15T00:00:00.000Z","recipientCount":1250}}}},"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`.","operationId":"listCreatorMassMessages","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"]},"status":{"type":"string","enum":["SENT","UNSENT","SENDING","FAILED","MODERATED","SCHEDULED"],"description":"Current status of the mass message"},"price":{"type":["number","null"],"description":"Price in cents for pay-to-view content, or null if free"},"createdAt":{"type":["string","null"],"format":"date"},"publishedAt":{"type":["string","null"],"format":"date","description":"When the message was published/sent"},"scheduledAt":{"type":["string","null"],"format":"date","description":"When the message is scheduled to send, or null for non-scheduled messages"},"recipientCount":{"type":"number","description":"Number of recipients the message was sent to. 0 while the message is SCHEDULED — recipients are resolved at send time, so this only becomes final once the status leaves SCHEDULED."},"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)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ordered list of media UUIDs attached to this mass message (display order)"},"includedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]}},"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Deprecated alias of `smartListIds`. Will be removed in a future API version."},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["smartListIds","smartListUuids","customListUuids"],"description":"Smart and custom lists the mass message was sent to. Inner arrays are empty when none were used."},"excludedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]}},"smartListUuids":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Deprecated alias of `smartListIds`. Will be removed in a future API version."},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["smartListIds","smartListUuids","customListUuids"],"description":"Smart and custom lists excluded from the mass message. Inner arrays are empty when none were used."}},"required":["uuid","text","status","price","createdAt","publishedAt","scheduledAt","recipientCount","viewCount","purchaseCount","totalRevenue","mediaUuids","includedLists","excludedLists"]},"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","scheduledAt":null,"recipientCount":1250,"viewCount":890,"purchaseCount":156,"totalRevenue":78000,"mediaUuids":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"includedLists":{"smartListIds":["subscribers","auto_renewing"],"smartListUuids":["subscribers","auto_renewing"],"customListUuids":["f1e2d3c4-b5a6-9788-c0d1-e2f3a4b5c6d7"]},"excludedLists":{"smartListIds":[],"smartListUuids":[],"customListUuids":[]}},{"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","scheduledAt":null,"recipientCount":1180,"viewCount":720,"purchaseCount":0,"totalRevenue":0,"mediaUuids":[],"includedLists":{"smartListIds":["followers"],"smartListUuids":["followers"],"customListUuids":[]},"excludedLists":{"smartListIds":["muted"],"smartListUuids":["muted"],"customListUuids":[]}}],"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.","operationId":"deleteCreatorMassMessage","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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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.","operationId":"updateCreatorMassMessage","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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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","null"],"minimum":300},"includedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Smart list identifiers — fixed string types such as 'subscribers' or 'followers', not UUIDs. The deprecated alias `smartListUuids` is also accepted."},"customListUuids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"excludedLists":{"type":"object","properties":{"smartListIds":{"type":"array","items":{"type":"string","enum":["subscribers","auto_renewing","non_renewing","followers","free_trial_subscribers","expired_subscribers","spent_more_than_50","muted","creators"]},"description":"Smart list identifiers — fixed string types such as 'subscribers' or 'followers', not UUIDs. The deprecated alias `smartListUuids` is also accepted."},"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).","operationId":"listCreatorMessages","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"]},"sentAt":{"type":["string","null"],"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","null"]},"mediaType":{"type":["string","null"],"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)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the media item shown for free as a preview of this pay-to-view message, or null when no free preview was configured. Mirrors the `mediaPreviewUuid` set when sending the message."},"gif":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The GIF provider's durable identifier for this GIF. Stable across renditions; use it to de-duplicate or re-resolve the GIF."},"format":{"type":"string","enum":["GIF","WEBP","MP4","WEBM"],"description":"Encoding of the asset at `url`. Only `GIF` and `WEBP` are produced today, and both render in a plain <img> tag."},"title":{"type":["string","null"],"description":"Human-readable GIF title, suitable as alt text."},"url":{"type":["string","null"],"description":"Hotlink URL of the GIF, served from the provider's CDN — Fanvue does not host or proxy the asset. Null when the URL is temporarily withheld; the message is still a GIF message, so render a placeholder at `width`/`height` rather than treating it as empty."},"width":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic width of the asset at `url`, in pixels"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic height of the asset at `url`, in pixels"}},"required":["id","format","title","url","width","height"],"description":"The third-party GIF attached to this message, or null for an ordinary message. A GIF message carries no media and no price, but `text` may be set — a GIF can be sent with a caption."},"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"]},"pricing":{"type":["object","null"],"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","null"],"format":"date","description":"Timestamp when this message was purchased, or null if not purchased"},"tipSource":{"type":["string","null"],"enum":["chat","post","media_link"],"description":"For TIP messages, where the tip originated: 'chat' (direct in-chat tip), 'post' (tipped a feed post) or 'media_link' (tipped via a shared media link). Null for non-tip messages."},"sentByUserId":{"type":["string","null"],"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"},"appUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the third-party app that created this message through the public API. Null when the message was sent from the Fanvue dashboard, and for every message sent before app attribution was recorded."},"isRead":{"type":"boolean","description":"Whether the message has been read by the recipient"}},"required":["uuid","text","sentAt","sender","recipient","hasMedia","mediaType","mediaUuids","mediaPreviewUuid","gif","type","pricing","purchasedAt","tipSource","sentByUserId","appUuid","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":[],"mediaPreviewUuid":null,"gif":null,"pricing":null,"purchasedAt":null,"tipSource":null,"sentByUserId":null,"appUuid":"f6a7b8c9-0123-4567-89ab-cdef01234567","isRead":true},{"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"],"mediaPreviewUuid":"c3d4e5f6-a7b8-9012-cdef-345678901234","gif":null,"pricing":{"USD":{"price":500}},"purchasedAt":"2024-01-15T00:00:00.000Z","tipSource":null,"sentByUserId":null,"appUuid":null,"isRead":true},{"uuid":"c3d4e5f6-7890-1234-5678-9abcdef01234","text":"Thanks for the tip! 💖","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":"TIP","hasMedia":false,"mediaType":null,"mediaUuids":[],"mediaPreviewUuid":null,"gif":null,"pricing":{"USD":{"price":1000}},"purchasedAt":null,"tipSource":"post","sentByUserId":null,"appUuid":null,"isRead":true},{"uuid":"d4e5f6a7-8901-2345-6789-abcdef012345","text":"Check out my new exclusive content 🔥","sentAt":"2024-01-14T00: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":{},"type":"BROADCAST","hasMedia":true,"mediaType":"image","mediaUuids":["b2c3d4e5-f6a7-8901-bcde-f12345678901"],"mediaPreviewUuid":null,"gif":null,"pricing":null,"purchasedAt":null,"tipSource":null,"sentByUserId":null,"appUuid":null,"isRead":false},{"uuid":"e5f6a7b8-9012-3456-789a-bcdef0123456","text":null,"sentAt":"2024-01-14T00: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":false,"mediaType":null,"mediaUuids":[],"mediaPreviewUuid":null,"gif":{"id":"excited-happy-dance-xY7bQ","format":"WEBP","title":"excited happy dance","url":"https://cdn.klipy.com/excited-happy-dance-xY7bQ/md.webp","width":480,"height":360},"pricing":null,"purchasedAt":null,"tipSource":null,"sentByUserId":null,"appUuid":null,"isRead":false}],"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.","operationId":"updateCreatorChat","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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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```","operationId":"listCreatorChatMedia","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"}],"security":[{"BearerAuth":["read:creator","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"],"format":"date"},"sentAt":{"type":["string","null"],"format":"date"},"ownerUuid":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["variantType","displayPosition","width","height","lengthMs"]}},"purchasedAt":{"type":["string","null"],"format":"date","description":"Timestamp when the fan purchased the media's source message, or null if not purchased."},"pricing":{"type":["object","null"],"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Listed price of the media's source pay-to-view message, or null if free. This does not reflect discounts — see `amountPaid` for what the fan actually paid."},"amountPaid":{"type":["object","null"],"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Amount the fan actually paid to unlock the media's source message, after any discount. Null when not purchased (see `purchasedAt`) or free."}},"required":["uuid","messageUuid","mediaType","created_at","sentAt","ownerUuid","name"]}},"nextCursor":{"type":["string","null"],"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}],"purchasedAt":"2024-01-15T00:00:00.000Z","pricing":{"USD":{"price":1000}},"amountPaid":{"USD":{"price":700}}},{"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}],"purchasedAt":null,"pricing":null,"amountPaid":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<Note>The `mediaUuids` query parameter is required and accepts up to 20 UUIDs.</Note>","operationId":"getCreatorMessageMediaByUuids","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"}],"security":[{"BearerAuth":["read:creator","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"responses":{"200":{"description":"Resolved media payload map","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"type":["object","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"messageUuid":{"type":"string","format":"uuid"},"mediaType":{"type":"string","enum":["image","video","audio","document","unknown"]},"created_at":{"type":["string","null"],"format":"date"},"sentAt":{"type":["string","null"],"format":"date"},"ownerUuid":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["variantType","displayPosition","width","height","lengthMs"]}},"purchasedAt":{"type":["string","null"],"format":"date","description":"Timestamp when the fan purchased the media's source message, or null if not purchased."},"pricing":{"type":["object","null"],"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Listed price of the media's source pay-to-view message, or null if free. This does not reflect discounts — see `amountPaid` for what the fan actually paid."},"amountPaid":{"type":["object","null"],"properties":{"USD":{"type":"object","properties":{"price":{"type":"number","description":"Price in cents"}},"required":["price"]}},"required":["USD"],"description":"Amount the fan actually paid to unlock the media's source message, after any discount. Null when not purchased (see `purchasedAt`) or free."}},"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}],"purchasedAt":"2024-01-15T00:00:00.000Z","pricing":{"USD":{"price":1000}},"amountPaid":{"USD":{"price":700}}},"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}/chats/unread":{"get":{"summary":"Get unread chats, messages, and notifications count for a creator","description":"Returns the count of unread chats, total unread messages, and unread notifications by type for the specified creator.","operationId":"getCreatorUnreadChatsCount","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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 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}/chats/statuses":{"post":{"summary":"Get online statuses for multiple users as a creator","description":"Returns the online status and last seen timestamp for multiple users in a single request, from the perspective of the specified creator.\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":"getCreatorBatchStatuses","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"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","null"],"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 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}/chats/messages/batch":{"post":{"summary":"Get messages from multiple chats in bulk for a creator","description":"Returns the most recent messages for up to 50 chats in a single request for the specified creator, keyed by the input chat UUID (the counterpart user UUID).\n\nThis is the bulk counterpart to `GET /creators/{creatorUserUuid}/chats/{userUuid}/messages`. Per-key errors are reported inside the 200 response body so a single unreachable chat never collapses the whole request.\n\n<Note>Maximum 50 chat UUIDs per request. Failed keys are reported as `{ \"error\": \"not_found\" }`.</Note>\n\n<Note>Read-only: fetching messages in bulk does not mutate read state — messages are not marked read and `isRead` reflects each message's state at read time.</Note>","operationId":"creatorMessagesBatch","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator","read:chat"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chatUuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"description":"Array of chat UUIDs (counterpart user UUIDs) to fetch messages for (1-50)"},"sinceMessageUuid":{"type":"string","format":"uuid","description":"Optional cursor for incremental walks: returns only messages strictly after this message's publish date in each chat"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Maximum messages to return per chat (1-50, default: 20)"}},"required":["chatUuids"]}}}},"responses":{"200":{"description":"Per-chat messages or error for each requested chat. Always 200 when the request itself is valid, even if every key fails.","content":{"application/json":{"schema":{"type":"object","properties":{"byChat":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"text":{"type":["string","null"]},"sentAt":{"type":["string","null"],"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","null"]},"mediaType":{"type":["string","null"],"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)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the media item shown for free as a preview of this pay-to-view message, or null when no free preview was configured. Mirrors the `mediaPreviewUuid` set when sending the message."},"gif":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The GIF provider's durable identifier for this GIF. Stable across renditions; use it to de-duplicate or re-resolve the GIF."},"format":{"type":"string","enum":["GIF","WEBP","MP4","WEBM"],"description":"Encoding of the asset at `url`. Only `GIF` and `WEBP` are produced today, and both render in a plain <img> tag."},"title":{"type":["string","null"],"description":"Human-readable GIF title, suitable as alt text."},"url":{"type":["string","null"],"description":"Hotlink URL of the GIF, served from the provider's CDN — Fanvue does not host or proxy the asset. Null when the URL is temporarily withheld; the message is still a GIF message, so render a placeholder at `width`/`height` rather than treating it as empty."},"width":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic width of the asset at `url`, in pixels"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Intrinsic height of the asset at `url`, in pixels"}},"required":["id","format","title","url","width","height"],"description":"The third-party GIF attached to this message, or null for an ordinary message. A GIF message carries no media and no price, but `text` may be set — a GIF can be sent with a caption."},"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"]},"pricing":{"type":["object","null"],"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","null"],"format":"date","description":"Timestamp when this message was purchased, or null if not purchased"},"tipSource":{"type":["string","null"],"enum":["chat","post","media_link"],"description":"For TIP messages, where the tip originated: 'chat' (direct in-chat tip), 'post' (tipped a feed post) or 'media_link' (tipped via a shared media link). Null for non-tip messages."},"sentByUserId":{"type":["string","null"],"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"},"appUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the third-party app that created this message through the public API. Null when the message was sent from the Fanvue dashboard, and for every message sent before app attribution was recorded."},"isRead":{"type":"boolean","description":"Whether the message has been read by the recipient"}},"required":["uuid","text","sentAt","sender","recipient","hasMedia","mediaType","mediaUuids","mediaPreviewUuid","gif","type","pricing","purchasedAt","tipSource","sentByUserId","appUuid","isRead"]}},"hasMore":{"type":"boolean","description":"Whether more messages exist beyond the returned set (older than `oldestMessageUuid` for the default newest-first read, or in the queried range for incremental walks)"},"oldestMessageUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the oldest message in the returned batch, or null if no messages were returned"}},"required":["messages","hasMore","oldestMessageUuid"]},{"type":"object","properties":{"error":{"type":"string","enum":["forbidden","not_found","internal"]}},"required":["error"]}]},"description":"Map of input chat UUID to messages or a per-key error"}},"required":["byChat"]},"example":{"byChat":{"b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7":{"messages":[{"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":[],"mediaPreviewUuid":null,"gif":null,"pricing":null,"purchasedAt":null,"sentByUserId":null,"appUuid":"f6a7b8c9-0123-4567-89ab-cdef01234567","isRead":true}],"hasMore":true,"oldestMessageUuid":"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"},"c3d4e5f6-7890-1234-5678-9abcdef01234":{"error":"not_found"}}}}}},"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}/chats/{userUuid}/messages/{messageUuid}":{"delete":{"summary":"Delete a message as a creator","description":"Delete/unsend a previously sent message from a creator's chat conversation.\n\nOnly messages sent by the creator can be deleted. Messages that have been purchased (paid content) cannot be deleted. Mass messages cannot be deleted via this endpoint.","operationId":"deleteCreatorMessage","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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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"}}}},"/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.","operationId":"getCreatorMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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","description":"Case-insensitive substring match on the media name."},"required":false,"description":"Case-insensitive substring match on the media name.","name":"name","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter to media created on or after this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-20T00:00:00Z)."},"required":false,"description":"Filter to media created on or after this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter to media created before this ISO 8601 datetime (non-inclusive, with optional timezone offset)."},"required":false,"description":"Filter to media created before this ISO 8601 datetime (non-inclusive, with optional timezone offset).","name":"endDate","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}],"security":[{"BearerAuth":["read:creator","read:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"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"},"total":{"type":"integer","description":"Total number of media items matching the query across all pages"}},"required":["page","size","hasMore","total"],"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,"tags":{"description":"Behind-the-scenes shot at sunset on a beach.","tags":["beach","sunset","outdoors"],"nsfwCategory":[],"sexActs":[],"bodyParts":[],"people":["solo woman"],"sexObjects":[],"setting":["beach","sunset"],"position":[],"skinColor":[],"bodyType":[],"hairColor":["blonde"],"otherTags":[],"importantTags":["beach"],"isNsfw":false,"mediaType":"video"},"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,"total":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"}}}},"/creators/{creatorUserUuid}/media/bulk":{"get":{"summary":"Get bulk media by UUIDs for a creator","description":"Returns multiple media items owned by the specified creator in a single request.\n\n<Note>Maximum 20 media UUIDs per request.</Note>","operationId":"getCreatorBulkMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string"},"required":true,"name":"mediaUuids","in":"query"},{"schema":{"type":"string"},"required":false,"name":"variants","in":"query"}],"security":[{"BearerAuth":["read:creator","read:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"required":["uuid","status","createdAt","caption","description","name","mediaType","recommendedPrice"]},{"type":"null"}]},"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,"tags":{"description":"Behind-the-scenes shot at sunset on a beach.","tags":["beach","sunset","outdoors"],"nsfwCategory":[],"sexActs":[],"bodyParts":[],"people":["solo woman"],"sexObjects":[],"setting":["beach","sunset"],"position":[],"skinColor":[],"bodyType":[],"hairColor":["blonde"],"otherTags":[],"importantTags":["beach"],"isNsfw":false,"mediaType":"image"},"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"},"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>","operationId":"getCreatorMediaByUuid","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}],"security":[{"BearerAuth":["read:creator","read:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"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,"tags":{"description":"Behind-the-scenes shot at sunset on a beach.","tags":["beach","sunset","outdoors"],"nsfwCategory":[],"sexActs":[],"bodyParts":[],"people":["solo woman"],"sexObjects":[],"setting":["beach","sunset"],"position":[],"skinColor":[],"bodyType":[],"hairColor":["blonde"],"otherTags":[],"importantTags":["beach"],"isNsfw":false,"mediaType":"image"},"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"}}},"patch":{"summary":"Update a creator's media name, caption and recommended price","description":"Update the name, caption and/or recommended price of a media item owned by the\n    specified creator.\n\n    Only `name`, `caption` and `recommendedPrice` can be changed. Omit a field to leave it\n    unchanged, or pass `null` to clear it. At least one field must be provided.","operationId":"updateCreatorMedia","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"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Display name. Pass null to clear it; omit to leave unchanged."},"caption":{"type":["string","null"],"maxLength":5000,"description":"Caption. Pass null to clear it; omit to leave unchanged."},"recommendedPrice":{"type":["integer","null"],"minimum":0,"maximum":50000,"description":"Recommended price in cents. Pass null to clear it; omit to leave unchanged."}}}}}},"responses":{"200":{"description":"Updated media item","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"caption":{"type":["string","null"]},"recommendedPrice":{"type":["number","null"]}},"required":["uuid","name","caption","recommendedPrice"]},"example":{"uuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","name":"Beach photoshoot","caption":"Golden hour by the sea 🌅","recommendedPrice":1500}}}},"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"}}},"delete":{"summary":"Delete a creator's media from the vault","description":"Soft-deletes a media item from the specified creator's vault, on-behalf of the creator.\n\n    The media is detached from any vault folders and removed from vault listings.\n    Copies already distributed elsewhere (sent in messages, attached to posts, or\n    previously purchased) are not affected and remain accessible to their recipients.","operationId":"deleteCreatorMedia","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"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"responses":{"204":{"description":"Media deleted from vault"},"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/links/{uuid}/purchased":{"get":{"summary":"Check if a creator has purchased a media link","description":"Returns whether the specified creator has a paid invoice for the given media link.\n\nReturns 404 if no media link with the given UUID exists.","operationId":"getCreatorMediaLinkPurchaseStatus","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"}],"security":[{"BearerAuth":["read:creator","read:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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"}}}},"/creators/{creatorUserUuid}/media/{uuid}/grant":{"post":{"summary":"Grant a consumer access to a creator's media item","description":"Grant a specific consumer access to a piece of media owned by the specified creator.\n    The grant is idempotent: repeated calls with the same parameters return the existing entitlement.","operationId":"grantCreatorMedia","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"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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"}}}},"/creators/{creatorUserUuid}/media/{uuid}/entitled":{"get":{"summary":"Get media for an entitled consumer of a creator","description":"Returns a media item owned by the specified creator with signed variant URLs, but only if\n    the specified consumer 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>","operationId":"getCreatorEntitledMedia","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 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}],"security":[{"BearerAuth":["read:creator","read:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"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,"tags":{"description":"Behind-the-scenes shot at sunset on a beach.","tags":["beach","sunset","outdoors"],"nsfwCategory":[],"sexActs":[],"bodyParts":[],"people":["solo woman"],"sexObjects":[],"setting":["beach","sunset"],"position":[],"skinColor":[],"bodyType":[],"hairColor":["blonde"],"otherTags":[],"importantTags":["beach"],"isNsfw":false,"mediaType":"image"},"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. Reversals are included as `refund`/`chargeback` rows with negative gross (matching /insights/spending); filter them with `source`.","operationId":"getCreatorEarnings","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":"array","items":{"type":"string"},"description":"Comma-separated transaction order IDs (max 100)"},"required":false,"description":"Comma-separated transaction order IDs to fetch (max 100). Use to re-fetch specific transactions by ID and pick up status changes. Combines with the other filters; normal pagination still applies.","name":"transactionOrderIds","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,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused."},"required":false,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.","name":"size","in":"query"}],"security":[{"BearerAuth":["read:creator","read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"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","null"],"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"},"reversedTransactionOrderId":{"type":"string","description":"Only on `refund` and `chargeback` rows: the `transactionOrderId` of the original transaction this row reverses. A reversal never rewrites the original transaction, so use this to link the two."},"messageUuid":{"type":"string","format":"uuid","description":"Message UUID when source is message (e.g. paid chat or broadcast message). Also present on tip rows, where it identifies the chat message Fanvue writes into the thread to record the tip — including for tips sent on a post. On a tip it is therefore not a signal that the tip came from a chat; use `tipContext` and `postUuid` for that."},"messageType":{"type":"string","enum":["AUTOMATED_CANCELED","AUTOMATED_NEW_FOLLOWER","AUTOMATED_NEW_PURCHASE","AUTOMATED_NEW_SUBSCRIBER","AUTOMATED_RE_SUBSCRIBED","AUTOMATED_RENEWED","AUTOMATED_FIRST_MESSAGE_REPLY","AUTOMATED_CHAT_MESSAGE_REPLY","BROADCAST","CHAT_TEXT_GENERATION","CHAT_TEXT_REWRITE","CHAT_TEXT_REPLY","GHOST_PROMOTION","MARKETING_KYC","TIP","LOCKED_MESSAGE_UNLOCKED","VOICE_CALL","SINGLE_RECIPIENT"],"description":"Underlying chat message type when source is message. Same values as the `type` field on the messages API — e.g. SINGLE_RECIPIENT (1-to-1 DM), BROADCAST / GHOST_PROMOTION (mass message), AUTOMATED_* (automated message). Use it to distinguish direct, mass, and automated message earnings."},"postUuid":{"type":"string","format":"uuid","description":"Post UUID when source is post"},"tipContext":{"type":"string","enum":["post","message"],"description":"Context of a tip when source is tip. `post` when the tip was sent on a post — `postUuid` identifies which. `message` for every other tip. Read `message` as 'not on a post' rather than 'in a chat': there is deliberately no `profile` value, because Fanvue does not record which surface a fan tipped from, so a tip sent in a chat thread and a tip sent from a creator profile are indistinguishable and both report `message`. Do not treat `message` as evidence of a chat origin when attributing revenue. Buckets identically to the `context` field on the tip.new webhook."},"user":{"type":["object","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"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","null"],"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","tipContext":"message","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"}},{"date":"2024-01-14T00:00:00.000Z","gross":2500,"net":2125,"currency":"USD","source":"message","transactionOrderId":"FV-ORDER-126","transactionOrderStatus":"availableForPayout","messageUuid":"b7c8d9e0-1234-5678-9abc-def012345678","messageType":"BROADCAST","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":"refund","transactionOrderId":"FV-ORDER-125","transactionOrderStatus":"availableForPayout","reversedTransactionOrderId":"FV-ORDER-124","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.","operationId":"getCreatorEarningsSummary","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"}],"security":[{"BearerAuth":["read:creator","read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"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","null"]},"netChangePercentage":{"type":["number","null"]}},"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","null"]},"endDate":{"type":["string","null"]},"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/earnings/percentile":{"get":{"summary":"Get earnings percentile for a creator","description":"Returns the earnings percentile bucket the specified creator falls into based on their gross earnings over the last 30 days.\n\nThe value is a decimal percentile where lower numbers indicate higher rank (e.g. `0.01` means top 0.01% of earners, `99.50` is near the bottom).","operationId":"getCreatorEarningsPercentile","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator","read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"responses":{"200":{"description":"Earnings percentile for the specified creator","content":{"application/json":{"schema":{"type":"object","properties":{"percentile":{"type":"number","description":"Earnings percentile (decimal) the creator falls into based on their gross earnings over the last 30 days. Lower values indicate higher rank: 0.01 = top 0.01% of earners, 99.50 ≈ bottom. Values are not constrained to whole numbers — bucket granularity is determined by the lookup table."}},"required":["percentile"]},"example":{"percentile":12.5}}}},"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/unsubscribe-reasons":{"get":{"summary":"Get unsubscribe reasons for a creator","description":"Returns a breakdown of why fans are unsubscribing from the specified creator, based on exit-survey data.\n\nThis is the same fan-health data surfaced in the Creator Agent. It is aggregated weekly (not real-time): `currentWeekCount` covers the most recent snapshot period and `rollingCount` spans the last 12 weeks.\n\nReasons returned: `too_expensive`, `not_enough_content`, `content_not_expected`, `creator_not_active`, and `other`. The `*Total` fields count all surveys in the window and may exceed the sum of the listed reasons.","operationId":"getCreatorUnsubscribeReasons","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"date-time","description":"ISO 8601 datetime anchoring the current-week window. Counts are aggregated on weekly fan-health snapshots, so this is snapped to the snapshot boundary. If omitted, defaults to the most recent snapshot period."},"required":false,"description":"ISO 8601 datetime anchoring the current-week window. Counts are aggregated on weekly fan-health snapshots, so this is snapped to the snapshot boundary. If omitted, defaults to the most recent snapshot period.","name":"periodStart","in":"query"}],"security":[{"BearerAuth":["read:creator","read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"responses":{"200":{"description":"Creator unsubscribe reasons breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"reasons":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","description":"Exit-survey reason. One of: too_expensive, not_enough_content, content_not_expected, creator_not_active, other."},"currentWeekCount":{"type":"integer","description":"Number of fans citing this reason in the most recent snapshot week"},"rollingCount":{"type":"integer","description":"Number of fans citing this reason across the last 12 weeks"}},"required":["reason","currentWeekCount","rollingCount"]},"description":"Per-reason counts. Based on exit surveys, aggregated weekly — not real-time."},"currentWeekTotal":{"type":"integer","description":"Total exit surveys in the most recent snapshot week (across all reasons)"},"rollingTotal":{"type":"integer","description":"Total exit surveys across the last 12 weeks (across all reasons)"}},"required":["reasons","currentWeekTotal","rollingTotal"]},"example":{"reasons":[{"reason":"too_expensive","currentWeekCount":3,"rollingCount":28},{"reason":"not_enough_content","currentWeekCount":2,"rollingCount":19},{"reason":"content_not_expected","currentWeekCount":1,"rollingCount":11},{"reason":"creator_not_active","currentWeekCount":0,"rollingCount":6},{"reason":"other","currentWeekCount":1,"rollingCount":9}],"currentWeekTotal":7,"rollingTotal":73}}}},"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/fan-retention-summary":{"get":{"summary":"Get fan retention summary for a creator","description":"Returns the specified creator's weekly fan-health snapshots, including paid/free active fans, churn, retention, reactivation, revenue retention, LTV, free-to-paid conversion, and engagement metrics. Snapshots are computed weekly by the data warehouse (not real-time); the most recent snapshot may be up to 7 days old.","operationId":"getCreatorFanRetentionSummary","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":12,"default":6,"description":"Number of most-recent weekly snapshots to return (1-12, default: 6)"},"required":false,"description":"Number of most-recent weekly snapshots to return (1-12, default: 6)","name":"periods","in":"query"}],"security":[{"BearerAuth":["read:creator","read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"responses":{"200":{"description":"Weekly fan retention snapshots","content":{"application/json":{"schema":{"type":"object","properties":{"snapshots":{"type":"array","items":{"type":"object","properties":{"periodStart":{"type":"string","format":"date-time","description":"Start of the weekly snapshot period as a UTC ISO 8601 datetime string"},"paidActiveFansCount":{"type":"number","description":"Paid (subscribed) active fans at the end of the week"},"prevPaidActiveFansCount":{"type":"number","description":"Paid active fans in the previous week"},"paidChurnedFansCount":{"type":"number","description":"Paid fans who churned during the week"},"paidRetainedFansCount":{"type":"number","description":"Paid fans retained from the previous week"},"paidNewFansCount":{"type":"number","description":"Net-new paid fans gained during the week"},"paidReactivatedFansCount":{"type":"number","description":"Previously churned paid fans who returned"},"paidFanChurnRate":{"type":"number","description":"Paid fan churn rate for the week (0-1)"},"paidFanNrr":{"type":"number","description":"Net revenue retention for paid fans"},"paidReactivationRate":{"type":"number","description":"Paid fan reactivation rate for the week"},"revenueCurrent":{"type":"number","description":"Subscription revenue this week, in USD cents"},"revenuePrevious":{"type":"number","description":"Subscription revenue the previous week, in USD cents"},"revenueRetained":{"type":"number","description":"Revenue from retained fans, in USD cents"},"revenueLost":{"type":"number","description":"Revenue lost to churn, in USD cents"},"revenueNewFans":{"type":"number","description":"Revenue from new fans, in USD cents"},"revenueReactivatedFans":{"type":"number","description":"Revenue from reactivated fans, in USD cents"},"ltvSimple":{"type":"number","description":"Simple lifetime value estimate, in USD cents"},"ltvWeighted":{"type":"number","description":"Churn-weighted lifetime value estimate, in USD cents"},"totalUniqueFans":{"type":"number","description":"Total unique fans (paid + free)"},"freeActiveFansCount":{"type":"number","description":"Free active fans at the end of the week"},"freeRetainedFansCount":{"type":"number","description":"Free fans retained from the previous week"},"freeNewFansCount":{"type":"number","description":"Net-new free fans gained during the week"},"freeReactivatedFansCount":{"type":"number","description":"Previously churned free fans who returned"},"freeChurnedFansCount":{"type":"number","description":"Free fans who churned during the week"},"freeFanChurnRate":{"type":"number","description":"Free fan churn rate for the week (0-1)"},"freeToPaidConversionCount":{"type":"number","description":"Free fans who converted to paid during the week"},"totalActiveFansCount":{"type":"number","description":"Total active fans (paid + free)"},"weeklyPostCount":{"type":"number","description":"Posts published during the week"},"weeklyPostingDays":{"type":"number","description":"Distinct days the creator posted"},"weeklySubscriberOnlyPosts":{"type":"number","description":"Subscriber-only posts published"},"weeklyFreePosts":{"type":"number","description":"Free posts published"},"weeklyPpvPosts":{"type":"number","description":"Pay-per-view posts published"},"weeklyAvgMediaPerPost":{"type":"number","description":"Average media attachments per post"},"weeklyPctPostsWithMedia":{"type":"number","description":"Share of posts containing media (0-1)"},"weeklyAvgLikesPerPost":{"type":"number","description":"Average likes per post"},"weeklyAvgCommentsPerPost":{"type":"number","description":"Average comments per post"},"weeklySingleMessagesSent":{"type":"number","description":"One-to-one messages sent"},"weeklyBroadcastMessagesSent":{"type":"number","description":"Broadcast/mass messages sent"},"weeklyUniqueFansMessaged":{"type":"number","description":"Unique fans messaged"},"weeklyAvgResponseTimeHours":{"type":"number","description":"Average response time to fans, in hours"},"weeklyPctRespondedWithin1h":{"type":"number","description":"Share of fan messages answered within 1h (0-1)"},"weeklyPctRespondedWithin4h":{"type":"number","description":"Share of fan messages answered within 4h (0-1)"},"weeklyPctRespondedWithin12h":{"type":"number","description":"Share of fan messages answered within 12h (0-1)"},"weeklyFansRespondedCount":{"type":"number","description":"Fans the creator responded to"},"weeklyFanResponseRate":{"type":"number","description":"Share of fans responded to (0-1)"}},"required":["periodStart","paidActiveFansCount","prevPaidActiveFansCount","paidChurnedFansCount","paidRetainedFansCount","paidNewFansCount","paidReactivatedFansCount","paidFanChurnRate","paidFanNrr","paidReactivationRate","revenueCurrent","revenuePrevious","revenueRetained","revenueLost","revenueNewFans","revenueReactivatedFans","ltvSimple","ltvWeighted","totalUniqueFans","freeActiveFansCount","freeRetainedFansCount","freeNewFansCount","freeReactivatedFansCount","freeChurnedFansCount","freeFanChurnRate","freeToPaidConversionCount","totalActiveFansCount","weeklyPostCount","weeklyPostingDays","weeklySubscriberOnlyPosts","weeklyFreePosts","weeklyPpvPosts","weeklyAvgMediaPerPost","weeklyPctPostsWithMedia","weeklyAvgLikesPerPost","weeklyAvgCommentsPerPost","weeklySingleMessagesSent","weeklyBroadcastMessagesSent","weeklyUniqueFansMessaged","weeklyAvgResponseTimeHours","weeklyPctRespondedWithin1h","weeklyPctRespondedWithin4h","weeklyPctRespondedWithin12h","weeklyFansRespondedCount","weeklyFanResponseRate"]},"description":"Weekly fan-health snapshots, most recent first"}},"required":["snapshots"]},"example":{"snapshots":[{"periodStart":"2026-03-16T00:00:00.000Z","paidActiveFansCount":1240,"prevPaidActiveFansCount":1180,"paidChurnedFansCount":95,"paidRetainedFansCount":1085,"paidNewFansCount":120,"paidReactivatedFansCount":35,"paidFanChurnRate":0.08,"paidFanNrr":1.04,"paidReactivationRate":0.03,"revenueCurrent":1860000,"revenuePrevious":1770000,"revenueRetained":1627500,"revenueLost":142500,"revenueNewFans":180000,"revenueReactivatedFans":52500,"ltvSimple":18750,"ltvWeighted":21300,"totalUniqueFans":4820,"freeActiveFansCount":3580,"freeRetainedFansCount":3210,"freeNewFansCount":410,"freeReactivatedFansCount":60,"freeChurnedFansCount":300,"freeFanChurnRate":0.08,"freeToPaidConversionCount":48,"totalActiveFansCount":4820,"weeklyPostCount":9,"weeklyPostingDays":5,"weeklySubscriberOnlyPosts":4,"weeklyFreePosts":3,"weeklyPpvPosts":2,"weeklyAvgMediaPerPost":2.4,"weeklyPctPostsWithMedia":0.89,"weeklyAvgLikesPerPost":156,"weeklyAvgCommentsPerPost":23,"weeklySingleMessagesSent":540,"weeklyBroadcastMessagesSent":3,"weeklyUniqueFansMessaged":310,"weeklyAvgResponseTimeHours":1.6,"weeklyPctRespondedWithin1h":0.62,"weeklyPctRespondedWithin4h":0.85,"weeklyPctRespondedWithin12h":0.95,"weeklyFansRespondedCount":290,"weeklyFanResponseRate":0.94},{"periodStart":"2026-03-09T00:00:00.000Z","paidActiveFansCount":1180,"prevPaidActiveFansCount":1150,"paidChurnedFansCount":88,"paidRetainedFansCount":1062,"paidNewFansCount":90,"paidReactivatedFansCount":28,"paidFanChurnRate":0.077,"paidFanNrr":1.02,"paidReactivationRate":0.024,"revenueCurrent":1770000,"revenuePrevious":1725000,"revenueRetained":1593000,"revenueLost":132000,"revenueNewFans":135000,"revenueReactivatedFans":42000,"ltvSimple":18200,"ltvWeighted":20600,"totalUniqueFans":4710,"freeActiveFansCount":3470,"freeRetainedFansCount":3160,"freeNewFansCount":360,"freeReactivatedFansCount":50,"freeChurnedFansCount":310,"freeFanChurnRate":0.082,"freeToPaidConversionCount":41,"totalActiveFansCount":4710,"weeklyPostCount":7,"weeklyPostingDays":4,"weeklySubscriberOnlyPosts":3,"weeklyFreePosts":3,"weeklyPpvPosts":1,"weeklyAvgMediaPerPost":2.1,"weeklyPctPostsWithMedia":0.86,"weeklyAvgLikesPerPost":142,"weeklyAvgCommentsPerPost":19,"weeklySingleMessagesSent":505,"weeklyBroadcastMessagesSent":2,"weeklyUniqueFansMessaged":295,"weeklyAvgResponseTimeHours":1.9,"weeklyPctRespondedWithin1h":0.58,"weeklyPctRespondedWithin4h":0.82,"weeklyPctRespondedWithin12h":0.93,"weeklyFansRespondedCount":276,"weeklyFanResponseRate":0.92}]}}}},"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}/insights/spending":{"get":{"summary":"Get spending reversal data for a creator","description":"Returns cursor-paginated reversal invoice data for the specified creator over a specified time period. Includes refund and chargeback transactions.","operationId":"getCreatorSpending","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/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,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused."},"required":false,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.","name":"size","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Restrict results to reversals belonging to a single fan on this creator"},"required":false,"description":"Restrict results to reversals belonging to a single fan on this creator","name":"fanUuid","in":"query"}],"security":[{"BearerAuth":["read:creator","read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"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","null"],"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","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"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","null"],"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) 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\n`newSubscribersCount` counts subscription **starts**, not distinct people: a returning fan who starts a new subscription is counted again. It also includes free trials, starts later refunded or charged back, fans who were later banned or deleted, and it spans profile subscriptions, checkout-link subscriptions and fan-experience subscriptions. Because of this it is normally higher than the \"New\" figure on the creator's in-app Insights dashboard, which counts first-ever profile subscribers only. Use this endpoint as the canonical daily acquisition figure.\n\n`startDate`/`endDate` offsets are honoured when selecting the window, but events are always bucketed into **UTC calendar days** — `date` is always UTC midnight. There is no timezone parameter on this endpoint, so a creator working in a non-UTC timezone should expect their local-day totals to differ from these buckets.","operationId":"getCreatorSubscribers","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). Inclusive. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days."},"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). Inclusive. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days.","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. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days."},"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. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days.","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,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused."},"required":false,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.","name":"size","in":"query"}],"security":[{"BearerAuth":["read:creator","read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"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":"Start of the UTC calendar day the events are bucketed on, as an ISO 8601 datetime string. Always UTC midnight (e.g., '2024-01-05T00:00:00.000Z'), regardless of any offset sent on startDate/endDate."},"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 subscription starts in this bucket. Counts every start, so a returning fan starting a new subscription counts again. Includes free trials and starts that were later refunded, and covers profile subscriptions, checkout-link subscriptions and fan-experience subscriptions."},"cancelledSubscribersCount":{"type":"number","description":"Number of subscription chains ending (final non-renewing expiry) in this bucket. This is a lapse, not the moment auto-renew was switched off."}},"required":["date","total","newSubscribersCount","cancelledSubscribersCount"]}},"nextCursor":{"type":["string","null"],"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.","operationId":"getCreatorTopSpenders","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:insights","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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}/insights/fans/{userUuid}":{"get":{"summary":"Get fan insights for a creator","description":"Returns detailed insights about a specific fan for the specified creator, including spending statistics, subscription status, and fan engagement metrics.","operationId":"getCreatorFanInsights","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Fan's UUID"},"required":true,"description":"Fan's UUID","name":"userUuid","in":"path"}],"security":[{"BearerAuth":["read:creator","read:insights","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"],"format":"date-time","description":"Date of the fan's last self-initiated purchase (ISO 8601), or null if there is none. Automatic renewals never move it, and a purchase later refunded or charged back still counts, so this is recency of intent. App Store purchases do not count as a purchase here."},"lastValidPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Same as `lastPurchaseAt` but skipping purchases later refunded or charged back, so this is recency of valid spend. Null when every self-initiated purchase was reversed."},"total":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount this fan paid across all transactions, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount this fan paid across all transactions, in USD cents. Excludes App Store purchases, which record a creator buying an app from its developer rather than a fan paying this creator."}},"required":["gross","total"]},"maxSinglePayment":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Largest single payment this fan made, in USD cents. Excludes App Store purchases."}},"required":["gross","total"]},"sources":{"type":"object","additionalProperties":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount paid by the fan for this source type, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount paid by the fan for this source type, in USD cents"},"count":{"type":"integer","description":"Number of purchases the fan made from this source, counting purchases later refunded or charged back. The denominator of `average`."},"netCount":{"type":"integer","description":"Number of purchases the fan made from this source that were not later refunded or charged back. The denominator of `netAverage`."},"average":{"type":"number","description":"Average purchase from this source, in USD cents: `total` divided by `count`, so refunded and charged-back purchases count on both sides. Not rounded."},"netAverage":{"type":["number","null"],"description":"Average surviving purchase from this source, in USD cents: the sum of this source's purchases that were never refunded or charged back, divided by `netCount`. Reversed purchases are dropped from both sides. `null` when `netCount` is 0. Not rounded."}},"required":["gross","total","count","netCount","average","netAverage"]},"description":"Breakdown of spending by source. `appStore` is never present: an App Store invoice records a creator buying an app from its developer, not a fan paying this creator. `fanExperience` is fan-to-creator spend and is included."}},"required":["lastPurchaseAt","lastValidPurchaseAt","total","maxSinglePayment","sources"]},"subscription":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date-time","description":"Date subscription was created (ISO 8601) or null if no subscription"},"renewsAt":{"type":["string","null"],"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","lastValidPurchaseAt":"2024-01-14T00:00:00.000Z","total":{"gross":27700,"total":27700},"maxSinglePayment":{"gross":5000,"total":5000},"sources":{"message":{"gross":15000,"total":15000,"count":6,"netCount":5,"average":2500,"netAverage":2600},"post":{"gross":8500,"total":8500,"count":5,"netCount":5,"average":1700,"netAverage":1700},"referral":{"gross":4200,"total":4200,"count":2,"netCount":2,"average":2100,"netAverage":2100}}},"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) 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/fans":{"get":{"summary":"Get fan insights in bulk for a creator","description":"Returns detailed insights for multiple fans of the specified creator in a single request.\n\n<Note>Maximum 20 fan UUIDs per request.</Note>","operationId":"getCreatorBulkFanInsights","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"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"}],"security":[{"BearerAuth":["read:creator","read:insights","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"responses":{"200":{"description":"Insight data about the creator's fans","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["subscriber","expired","follower","not_contactable"],"description":"Current fan status"},"spending":{"type":"object","properties":{"lastPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Date of the fan's last self-initiated purchase (ISO 8601), or null if there is none. Automatic renewals never move it, and a purchase later refunded or charged back still counts, so this is recency of intent. App Store purchases do not count as a purchase here."},"lastValidPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Same as `lastPurchaseAt` but skipping purchases later refunded or charged back, so this is recency of valid spend. Null when every self-initiated purchase was reversed."},"total":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount this fan paid across all transactions, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount this fan paid across all transactions, in USD cents. Excludes App Store purchases, which record a creator buying an app from its developer rather than a fan paying this creator."}},"required":["gross","total"]},"maxSinglePayment":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Largest single payment this fan made, in USD cents. Excludes App Store purchases."}},"required":["gross","total"]},"sources":{"type":"object","additionalProperties":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount paid by the fan for this source type, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount paid by the fan for this source type, in USD cents"},"count":{"type":"integer","description":"Number of purchases the fan made from this source, counting purchases later refunded or charged back. The denominator of `average`."},"netCount":{"type":"integer","description":"Number of purchases the fan made from this source that were not later refunded or charged back. The denominator of `netAverage`."},"average":{"type":"number","description":"Average purchase from this source, in USD cents: `total` divided by `count`, so refunded and charged-back purchases count on both sides. Not rounded."},"netAverage":{"type":["number","null"],"description":"Average surviving purchase from this source, in USD cents: the sum of this source's purchases that were never refunded or charged back, divided by `netCount`. Reversed purchases are dropped from both sides. `null` when `netCount` is 0. Not rounded."}},"required":["gross","total","count","netCount","average","netAverage"]},"description":"Breakdown of spending by source. `appStore` is never present: an App Store invoice records a creator buying an app from its developer, not a fan paying this creator. `fanExperience` is fan-to-creator spend and is included."}},"required":["lastPurchaseAt","lastValidPurchaseAt","total","maxSinglePayment","sources"]},"subscription":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date-time","description":"Date subscription was created (ISO 8601) or null if no subscription"},"renewsAt":{"type":["string","null"],"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","lastValidPurchaseAt":"2024-01-14T00:00:00.000Z","total":{"gross":27700,"total":27700},"maxSinglePayment":{"gross":5000,"total":5000},"sources":{"message":{"gross":15000,"total":15000,"count":6,"netCount":5,"average":2500,"netAverage":2600},"post":{"gross":8500,"total":8500,"count":5,"netCount":5,"average":1700,"netAverage":1700},"referral":{"gross":4200,"total":4200,"count":2,"netCount":2,"average":2100,"netAverage":2100}}},"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) 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/fans/batch":{"post":{"summary":"Get fan insights in bulk for a creator (POST batch)","description":"Returns detailed insights for up to 100 fans of the specified creator in a single request, keyed by the input fan UUID.\n\nPer-key errors are reported inside the 200 response body so a single forbidden or missing fan never collapses the whole request.\n\n<Note>Maximum 100 fan UUIDs per request. Failed keys are reported as `{ \"error\": \"forbidden\" | \"not_found\" | \"internal\" }`.</Note>","operationId":"batchCreatorFanInsights","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator","read:insights","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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 fan UUIDs to fetch insights for (1-100)"}},"required":["userUuids"]}}}},"responses":{"200":{"description":"Per-key insights or error for each requested fan. Always 200 when the request itself is valid, even if every key fails.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["subscriber","expired","follower","not_contactable"],"description":"Current fan status"},"spending":{"type":"object","properties":{"lastPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Date of the fan's last self-initiated purchase (ISO 8601), or null if there is none. Automatic renewals never move it, and a purchase later refunded or charged back still counts, so this is recency of intent. App Store purchases do not count as a purchase here."},"lastValidPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Same as `lastPurchaseAt` but skipping purchases later refunded or charged back, so this is recency of valid spend. Null when every self-initiated purchase was reversed."},"total":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount this fan paid across all transactions, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount this fan paid across all transactions, in USD cents. Excludes App Store purchases, which record a creator buying an app from its developer rather than a fan paying this creator."}},"required":["gross","total"]},"maxSinglePayment":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Largest single payment this fan made, in USD cents. Excludes App Store purchases."}},"required":["gross","total"]},"sources":{"type":"object","additionalProperties":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount paid by the fan for this source type, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount paid by the fan for this source type, in USD cents"},"count":{"type":"integer","description":"Number of purchases the fan made from this source, counting purchases later refunded or charged back. The denominator of `average`."},"netCount":{"type":"integer","description":"Number of purchases the fan made from this source that were not later refunded or charged back. The denominator of `netAverage`."},"average":{"type":"number","description":"Average purchase from this source, in USD cents: `total` divided by `count`, so refunded and charged-back purchases count on both sides. Not rounded."},"netAverage":{"type":["number","null"],"description":"Average surviving purchase from this source, in USD cents: the sum of this source's purchases that were never refunded or charged back, divided by `netCount`. Reversed purchases are dropped from both sides. `null` when `netCount` is 0. Not rounded."}},"required":["gross","total","count","netCount","average","netAverage"]},"description":"Breakdown of spending by source. `appStore` is never present: an App Store invoice records a creator buying an app from its developer, not a fan paying this creator. `fanExperience` is fan-to-creator spend and is included."}},"required":["lastPurchaseAt","lastValidPurchaseAt","total","maxSinglePayment","sources"]},"subscription":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date-time","description":"Date subscription was created (ISO 8601) or null if no subscription"},"renewsAt":{"type":["string","null"],"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"]},{"type":"object","properties":{"error":{"type":"string","enum":["forbidden","not_found","internal"]}},"required":["error"]}]},"description":"Map of input fan UUID to insights or a per-key error (forbidden, not_found, or internal)."},"example":{"11111111-1111-4111-8111-111111111111":{"status":"subscriber","spending":{"lastPurchaseAt":"2026-04-12T08:32:00.000Z","lastValidPurchaseAt":"2026-03-30T19:05:00.000Z","total":{"gross":12000,"total":12000},"maxSinglePayment":{"gross":5000,"total":5000},"sources":{"subscription":{"gross":7000,"total":7000,"count":7,"netCount":7,"average":1000,"netAverage":1000},"tips":{"gross":5000,"total":5000,"count":2,"netCount":0,"average":2500,"netAverage":null}}},"subscription":{"createdAt":"2026-01-15T00:00:00.000Z","renewsAt":"2026-06-15T00:00:00.000Z","autoRenewalEnabled":true}},"22222222-2222-4222-8222-222222222222":{"error":"not_found"},"33333333-3333-4333-9333-333333333333":{"error":"internal"}}}}},"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.","operationId":"createCreatorUploadSession","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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"]},"sizeBytes":{"type":"integer","exclusiveMinimum":0,"maximum":1610612736,"description":"Total size of the file in bytes. When provided, the response includes the exact `totalParts` to upload."}},"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"},"partSize":{"type":"integer","description":"Size in bytes of every part except the final one (which may be smaller)."},"maxParts":{"type":"integer","description":"Maximum number of parts allowed, derived from the maximum supported file size."},"totalParts":{"type":["integer","null"],"description":"Exact number of parts to upload, computed from `sizeBytes`. Null when `sizeBytes` was not provided — compute it client-side as ceil(fileSize / partSize)."}},"required":["mediaUuid","uploadId","partSize","maxParts","totalParts"]},"example":{"mediaUuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","uploadId":"abc123XYZ789multipart","partSize":6291456,"maxParts":854,"totalParts":4}}}},"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.","operationId":"getCreatorUploadPartUrl","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","null"]},"required":false,"name":"partNumber","in":"path"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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.","operationId":"completeCreatorUploadSession","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"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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":{"get":{"summary":"Get posts for a creator","description":"Returns a paginated list of posts created by the specified creator. Posts are ordered by pinned status first, then by publication date (newest first).","operationId":"getCreatorPosts","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"},{"schema":{"type":"string","format":"date-time","description":"Only include posts created on or after this ISO 8601 datetime (e.g., 2024-10-20T00:00:00Z)."},"required":false,"description":"Only include posts created on or after this ISO 8601 datetime (e.g., 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include posts created before this ISO 8601 datetime (non-inclusive)."},"required":false,"description":"Only include posts created before this ISO 8601 datetime (non-inclusive).","name":"endDate","in":"query"}],"security":[{"BearerAuth":["read:post","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of posts for this creator","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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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":{"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 new post for a creator","description":"Create a new post on behalf of a creator with optional media, text, and pricing.","operationId":"createCreatorPost","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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}":{"get":{"summary":"Get a creator's post by UUID","description":"Returns a specific post owned by the specified creator by its UUID.","operationId":"getCreatorPostByUuid","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"},"required":true,"description":"UUID of the post to retrieve","name":"uuid","in":"path"}],"security":[{"BearerAuth":["read:post","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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 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.","operationId":"updateCreatorPost","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"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":["string","null"],"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","null"],"format":"uuid","description":"UUID of free preview media shown before unlock. Set to null to remove."},"price":{"type":["number","null"],"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","null"],"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","null"],"format":"date-time","description":"Date/time when the post expires (ISO 8601 format). Set to null to remove expiration."},"collectionUuids":{"type":["array","null"],"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"deleteCreatorPost","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"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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}/tips":{"get":{"summary":"Get tips for a creator's post","description":"Returns a paginated list of tips received on a specific post owned by the specified creator.","operationId":"getCreatorPostTips","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 tips for"},"required":true,"description":"UUID of the post to retrieve tips for","name":"uuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:post","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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","null"],"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"}}}},"/creators/{creatorUserUuid}/posts/{uuid}/likes":{"get":{"summary":"Get likes for a creator's post","description":"Returns a paginated list of likes received on a specific post owned by the specified creator.","operationId":"getCreatorPostLikes","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 likes for"},"required":true,"description":"UUID of the post to retrieve likes for","name":"uuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:post","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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"}}}},"/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.","operationId":"repostCreatorPost","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"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"pinCreatorPost","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"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"unpinCreatorPost","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"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"createCreatorPostComment","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"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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","null"],"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.","operationId":"getCreatorPostComments","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:post","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"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","null"],"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.","operationId":"deleteCreatorPostComment","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"}],"security":[{"BearerAuth":["write:post","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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.","operationId":"getCreatorSmartLists","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator","read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","creators"],"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},{"name":"Creators","uuid":"creators","count":100}]}}},"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.","operationId":"getCreatorSmartListMembers","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","creators"],"description":"Smart list unique identifier"},"required":true,"description":"Smart list unique identifier","name":"uuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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.","operationId":"getCreatorCustomLists","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"],"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"}}},"post":{"summary":"Create a custom list for a creator","description":"Create a new custom list for organizing the specified creator's contacts.","operationId":"createCreatorCustomList","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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","null"],"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 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"},"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"}}}},"/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.","operationId":"getCreatorCustomListMembers","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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 creator's custom list","description":"Update the name of an existing custom list for the specified creator.","operationId":"updateCreatorCustomList","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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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 creator's custom list","description":"Delete a custom list for the specified creator. All members will be removed from the list.","operationId":"deleteCreatorCustomList","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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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"}}}},"/creators/{creatorUserUuid}/chats/lists/custom/{uuid}/members":{"post":{"summary":"Add members to a creator's custom list","description":"Add one or more users to a custom list for the specified creator. Existing members will be skipped.","operationId":"addCreatorCustomListMembers","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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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"}}}},"/creators/{creatorUserUuid}/chats/lists/custom/{uuid}/members/{userUuid}":{"delete":{"summary":"Remove a member from a creator's custom list","description":"Remove a user from a custom list for the specified creator.","operationId":"removeCreatorCustomListMember","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":"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"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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"}}}},"/creators/{creatorUserUuid}/checkout-links/payments":{"get":{"summary":"List a creator's checkout-link payments","description":"List checkout-link payments for the specified creator, most recent first, with cursor-based pagination. Filter by your own `clientReferenceId` to reconcile a specific checkout, or by `status`. Webhooks remain the primary delivery mechanism; this endpoint is for reconciliation and recovering missed events.\n\n<Info>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `checkout_link.payment.succeeded`, `checkout_link.payment.pending`, `checkout_link.payment.failed` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/checkout/payments).\n</Info>","operationId":"listCreatorCheckoutLinkPayments","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"description":"Number of results to return (default 20, max 100)."},"required":false,"description":"Number of results to return (default 20, max 100).","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination."},"required":false,"description":"Cursor for pagination.","name":"cursor","in":"query"},{"schema":{"type":"string","description":"Filter to payments carrying this exact `client_reference_id`."},"required":false,"description":"Filter to payments carrying this exact `client_reference_id`.","name":"clientReferenceId","in":"query"},{"schema":{"type":"string","enum":["pending","succeeded","failed"],"description":"Filter to payments with this status."},"required":false,"description":"Filter to payments with this status.","name":"status","in":"query"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of checkout-link payments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"invoiceNumber":{"type":"string","description":"Fanvue's unique payment identifier. Use this as the idempotency key for fulfilment."},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"Settlement status of the payment."},"billingReason":{"type":"string","enum":["one_time","subscription_initial","subscription_renewal"],"description":"What the payment was for: a one-off purchase, the first payment of a subscription, or a subscription renewal. Matches the `billing_reason` on the checkout_link.payment.* webhook."},"clientReferenceId":{"type":["string","null"],"description":"The merchant-supplied reference passed at checkout via `?client_reference_id=`. Use it to match the payment to your own order/customer."},"gross":{"type":"number","description":"Gross amount the buyer paid, in minor units."},"net":{"type":["number","null"],"description":"Creator net amount after fees, in minor units."},"fees":{"type":"object","properties":{"fanvueFee":{"type":["number","null"],"description":"Fanvue fee, in minor units."},"transactionFee":{"type":["number","null"],"description":"Payment processing fee, in minor units."}},"required":["fanvueFee","transactionFee"]},"currency":{"type":["string","null"],"description":"ISO currency code of the amounts."},"transactionId":{"type":["string","null"],"description":"Payment processor transaction reference."},"createdAt":{"type":"string","format":"date-time","description":"When the payment was created."},"paidAt":{"type":["string","null"],"format":"date-time","description":"When the payment settled, if it did."},"checkoutLink":{"type":"object","properties":{"uuid":{"type":["string","null"],"description":"UUID of the checkout link used."},"name":{"type":["string","null"],"description":"Name of the checkout link / offer."},"productUuid":{"type":["string","null"],"description":"UUID of the purchased product."},"productPriceUuid":{"type":["string","null"],"description":"UUID of the purchased product price."}},"required":["uuid","name","productUuid","productPriceUuid"]},"purchaser":{"type":"object","properties":{"uuid":{"type":["string","null"],"description":"UUID of the purchasing Fanvue user."},"email":{"type":["string","null"],"description":"Email of the purchasing Fanvue user."}},"required":["uuid","email"]},"metadata":{"type":"object","additionalProperties":{},"description":"Arbitrary merchant metadata passed at checkout via `?metadata[key]=value`."}},"required":["invoiceNumber","status","billingReason","clientReferenceId","gross","net","fees","currency","transactionId","createdAt","paidAt","checkoutLink","purchaser","metadata"]}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null if none."}},"required":["data","nextCursor"]},"example":{"data":[{"invoiceNumber":"FVE-20260619-1234","status":"succeeded","billingReason":"one_time","clientReferenceId":"order_9f8c","gross":9999,"net":8000,"fees":{"fanvueFee":1500,"transactionFee":499},"currency":"USD","transactionId":"txn_abc123","createdAt":"2026-06-19T08:30:00.000Z","paidAt":"2026-06-19T08:30:05.000Z","checkoutLink":{"uuid":"0b3c0e4a-1f2d-4c8a-9a1b-3e5f7a9c1d2e","name":"Premium Coaching","productUuid":"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","productPriceUuid":"9z8y7x6w-5v4u-3t2s-1r0q-9p8o7n6m5l4k"},"purchaser":{"uuid":"7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f","email":"buyer@example.com"},"metadata":{"campaign":"summer"}}],"nextCursor":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}/checkout-links/payments/{invoiceNumber}":{"get":{"summary":"Get a creator's checkout-link payment by invoice number","description":"Fetch a single checkout-link payment by its Fanvue `invoiceNumber`, scoped to the specified creator. Returns 404 if the payment does not exist or does not belong to this creator.","operationId":"getCreatorCheckoutLinkPayment","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","description":"Fanvue payment identifier (invoice number)."},"required":true,"description":"Fanvue payment identifier (invoice number).","name":"invoiceNumber","in":"path"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"The checkout-link payment","content":{"application/json":{"schema":{"type":"object","properties":{"invoiceNumber":{"type":"string","description":"Fanvue's unique payment identifier. Use this as the idempotency key for fulfilment."},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"Settlement status of the payment."},"billingReason":{"type":"string","enum":["one_time","subscription_initial","subscription_renewal"],"description":"What the payment was for: a one-off purchase, the first payment of a subscription, or a subscription renewal. Matches the `billing_reason` on the checkout_link.payment.* webhook."},"clientReferenceId":{"type":["string","null"],"description":"The merchant-supplied reference passed at checkout via `?client_reference_id=`. Use it to match the payment to your own order/customer."},"gross":{"type":"number","description":"Gross amount the buyer paid, in minor units."},"net":{"type":["number","null"],"description":"Creator net amount after fees, in minor units."},"fees":{"type":"object","properties":{"fanvueFee":{"type":["number","null"],"description":"Fanvue fee, in minor units."},"transactionFee":{"type":["number","null"],"description":"Payment processing fee, in minor units."}},"required":["fanvueFee","transactionFee"]},"currency":{"type":["string","null"],"description":"ISO currency code of the amounts."},"transactionId":{"type":["string","null"],"description":"Payment processor transaction reference."},"createdAt":{"type":"string","format":"date-time","description":"When the payment was created."},"paidAt":{"type":["string","null"],"format":"date-time","description":"When the payment settled, if it did."},"checkoutLink":{"type":"object","properties":{"uuid":{"type":["string","null"],"description":"UUID of the checkout link used."},"name":{"type":["string","null"],"description":"Name of the checkout link / offer."},"productUuid":{"type":["string","null"],"description":"UUID of the purchased product."},"productPriceUuid":{"type":["string","null"],"description":"UUID of the purchased product price."}},"required":["uuid","name","productUuid","productPriceUuid"]},"purchaser":{"type":"object","properties":{"uuid":{"type":["string","null"],"description":"UUID of the purchasing Fanvue user."},"email":{"type":["string","null"],"description":"Email of the purchasing Fanvue user."}},"required":["uuid","email"]},"metadata":{"type":"object","additionalProperties":{},"description":"Arbitrary merchant metadata passed at checkout via `?metadata[key]=value`."}},"required":["invoiceNumber","status","billingReason","clientReferenceId","gross","net","fees","currency","transactionId","createdAt","paidAt","checkoutLink","purchaser","metadata"]},"example":{"invoiceNumber":"FVE-20260619-1234","status":"succeeded","billingReason":"one_time","clientReferenceId":"order_9f8c","gross":9999,"net":8000,"fees":{"fanvueFee":1500,"transactionFee":499},"currency":"USD","transactionId":"txn_abc123","createdAt":"2026-06-19T08:30:00.000Z","paidAt":"2026-06-19T08:30:05.000Z","checkoutLink":{"uuid":"0b3c0e4a-1f2d-4c8a-9a1b-3e5f7a9c1d2e","name":"Premium Coaching","productUuid":"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","productPriceUuid":"9z8y7x6w-5v4u-3t2s-1r0q-9p8o7n6m5l4k"},"purchaser":{"uuid":"7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f","email":"buyer@example.com"},"metadata":{"campaign":"summer"}}}}},"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}/checkout-links":{"get":{"summary":"List a creator's checkout links","description":"List the specified creator's checkout links, newest first. Soft-deleted links are excluded; disabled links are included with `status: disabled`. All amounts are integer minor units of the currency (e.g. cents).","operationId":"listCreatorCheckoutLinks","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of checkout links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Checkout link UUID"},"name":{"type":"string","description":"Creator-internal label for the link (derived from the product name)"},"description":{"type":["string","null"],"description":"Creator-internal note (null when unset). Fans never see it."},"url":{"type":["string","null"],"description":"Shareable checkout URL fans use to purchase"},"price":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents). 0 for free links."},"currency":{"type":"string","description":"ISO-4217 currency code of the price"},"isRecurring":{"type":"boolean","description":"Whether purchases create a recurring subscription"},"cycleLength":{"type":["integer","null"],"description":"Billing cycle length (null for one-off prices)"},"cycleUnit":{"type":["string","null"],"enum":["day","week","month","year"],"description":"Billing cycle unit (null for one-off prices)"},"productUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the product the link sells"},"productPriceUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the product price the link sells"},"status":{"type":"string","enum":["active","disabled"],"description":"active links can be purchased; disabled links reject checkout until re-enabled"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","name","description","url","price","currency","isRecurring","cycleLength","cycleUnit","productUuid","productPriceUuid","status","createdAt"]},"description":"The creator's checkout links, newest first"},"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":"b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e","name":"Coaching call","description":"Instagram bio link","url":"https://www.fanvue.com/checkout/fvcl_4WqZz1kXo9DdPp2sT7yRfM","price":1999,"currency":"USD","isRecurring":false,"cycleLength":null,"cycleUnit":null,"productUuid":"c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f","productPriceUuid":"d5e6f7a8-9b0c-4d1e-af2a-3b4c5d6e7f8a","status":"active","createdAt":"2024-01-15T00:00:00.000Z"},{"uuid":"e6f7a8b9-0c1d-4e2f-ba3b-4c5d6e7f8a9b","name":"Monthly membership","description":null,"url":"https://www.fanvue.com/checkout/fvcl_9XrYy2lWn8CcOq3tU6zSgN","price":2500,"currency":"USD","isRecurring":true,"cycleLength":1,"cycleUnit":"month","productUuid":"f7a8b9c0-1d2e-4f3a-8b4c-5d6e7f8a9b0c","productPriceUuid":"a8b9c0d1-2e3f-4a4b-9c5d-6e7f8a9b0c1d","status":"disabled","createdAt":"2024-01-14T00: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 checkout link for a creator","description":"Create a shareable checkout link on behalf of the specified creator, selling either an existing product price (`existing_price`), a new price on an existing product (`existing_product`), or a brand-new product (`new_product`).\n\nAll amounts are integer minor units of the currency (e.g. cents: 1999 = $19.99); the Fanvue dashboard displays the same prices in major units. Requires checkout links to be enabled for the creator.","operationId":"createCreatorCheckoutLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","maxLength":500,"description":"Internal note shown only in the creator dashboard. Fans never see it."},"redirectUrl":{"type":"string","format":"uri","description":"URL fans are redirected to after a successful purchase."},"source":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["existing_price"],"description":"Sell an existing product price through the new link."},"productPriceUuid":{"type":"string","format":"uuid","description":"UUID of the existing product price to sell."}},"required":["kind","productPriceUuid"]},{"type":"object","properties":{"kind":{"type":"string","enum":["existing_product"],"description":"Mint a new price on an existing product and sell it through the new link."},"productUuid":{"type":"string","format":"uuid","description":"UUID of the existing product to price."},"price":{"type":"object","properties":{"amount":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents: 1999 = $19.99). 0 creates a free link; paid links must be between 300 and 1000000 minor units ($3-$10,000). Note: the Fanvue dashboard displays prices in major units; this API always uses integer minor units."},"currency":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"USD","description":"3-letter uppercase ISO-4217 currency code. Defaults to USD."},"isRecurring":{"type":"boolean","description":"Whether purchases bill on a recurring cycle (subscription) or once. Recurring prices require a non-zero amount plus cycleLength and cycleUnit."},"cycleLength":{"type":"integer","exclusiveMinimum":0,"description":"Billing cycle length. Required (with cycleUnit) when isRecurring is true."},"cycleUnit":{"type":"string","enum":["day","week","month","year"],"description":"Billing cycle unit. Required (with cycleLength) when isRecurring is true."}},"required":["amount","isRecurring"]}},"required":["kind","productUuid","price"]},{"type":"object","properties":{"kind":{"type":"string","enum":["new_product"],"description":"Create a brand-new product with a price and sell it through the new link."},"product":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Product name. Must be unique (case-insensitive) among the creator's products."},"description":{"type":"string","maxLength":500,"description":"Optional product description."}},"required":["name"]},"price":{"type":"object","properties":{"amount":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents: 1999 = $19.99). 0 creates a free link; paid links must be between 300 and 1000000 minor units ($3-$10,000). Note: the Fanvue dashboard displays prices in major units; this API always uses integer minor units."},"currency":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"USD","description":"3-letter uppercase ISO-4217 currency code. Defaults to USD."},"isRecurring":{"type":"boolean","description":"Whether purchases bill on a recurring cycle (subscription) or once. Recurring prices require a non-zero amount plus cycleLength and cycleUnit."},"cycleLength":{"type":"integer","exclusiveMinimum":0,"description":"Billing cycle length. Required (with cycleUnit) when isRecurring is true."},"cycleUnit":{"type":"string","enum":["day","week","month","year"],"description":"Billing cycle unit. Required (with cycleLength) when isRecurring is true."}},"required":["amount","isRecurring"]}},"required":["kind","product","price"]}],"description":"What the link sells: an existing price (`existing_price`), a new price on an existing product (`existing_product`), or a brand-new product (`new_product`)."}},"required":["source"]}}}},"responses":{"201":{"description":"Checkout link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Checkout link UUID"},"name":{"type":"string","description":"Creator-internal label for the link (derived from the product name)"},"description":{"type":["string","null"],"description":"Creator-internal note (null when unset). Fans never see it."},"url":{"type":["string","null"],"description":"Shareable checkout URL fans use to purchase"},"price":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents). 0 for free links."},"currency":{"type":"string","description":"ISO-4217 currency code of the price"},"isRecurring":{"type":"boolean","description":"Whether purchases create a recurring subscription"},"cycleLength":{"type":["integer","null"],"description":"Billing cycle length (null for one-off prices)"},"cycleUnit":{"type":["string","null"],"enum":["day","week","month","year"],"description":"Billing cycle unit (null for one-off prices)"},"productUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the product the link sells"},"productPriceUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the product price the link sells"},"status":{"type":"string","enum":["active","disabled"],"description":"active links can be purchased; disabled links reject checkout until re-enabled"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","name","description","url","price","currency","isRecurring","cycleLength","cycleUnit","productUuid","productPriceUuid","status","createdAt"]},"example":{"uuid":"b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e","name":"Coaching call","description":"Instagram bio link","url":"https://www.fanvue.com/checkout/fvcl_4WqZz1kXo9DdPp2sT7yRfM","price":1999,"currency":"USD","isRecurring":false,"cycleLength":null,"cycleUnit":null,"productUuid":"c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f","productPriceUuid":"d5e6f7a8-9b0c-4d1e-af2a-3b4c5d6e7f8a","status":"active","createdAt":"2024-01-15T00: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}/checkout-links/{uuid}":{"patch":{"summary":"Enable or disable a creator's checkout link","description":"Toggle the specified creator's checkout link status. Disabling is reversible: the link's checkout page stops accepting purchases until it is set back to active. Deleted links cannot be re-enabled.","operationId":"updateCreatorCheckoutLinkStatus","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Checkout link UUID"},"required":true,"description":"Checkout link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","disabled"],"description":"Set to disabled to stop the link's checkout page (reversible), or active to re-enable it."}},"required":["status"]}}}},"responses":{"200":{"description":"Checkout link status updated","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Checkout link UUID"},"status":{"type":"string","enum":["active","disabled"],"description":"active links can be purchased; disabled links reject checkout until re-enabled"}},"required":["uuid","status"]},"example":{"uuid":"b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e","status":"disabled"}}}},"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 creator's checkout link","description":"Soft-delete the specified creator's checkout link so it can no longer be purchased or re-enabled. Deletion is terminal; past payments remain available on the payments endpoints.","operationId":"deleteCreatorCheckoutLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Checkout link UUID"},"required":true,"description":"Checkout link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Checkout 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"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"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.","operationId":"listCreatorTrackingLinks","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"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"}],"security":[{"BearerAuth":["read:tracking_links","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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, including clicks that were never matched to an account. This is why the count can exceed the number of users returned by the tracking-link users endpoint, which can only list identified clickers."},"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","null"],"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","null"],"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\nThe response `linkUrl` is the short slug (for example `fv-3`); the shareable URL is `https://www.fanvue.com/<handle>/<linkUrl>`. To attribute a click to a campaign or a record in your own system, append your own query parameters to that URL and read them back from the user-metadata endpoint. See the [tracking links guide](https://api.fanvue.com/docs/tutorials/tracking-links).","operationId":"createCreatorTrackingLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:tracking_links","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:tracking_links` — Create and delete tracking links.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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, including clicks that were never matched to an account. This is why the count can exceed the number of users returned by the tracking-link users endpoint, which can only list identified clickers."},"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","null"],"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\nOnly clicks that could be matched to an account appear here, so this list is a subset of the link's `clicks` count. A user who clicked without ever signing in cannot be identified and is omitted.\n\nUsers who clicked but never subscribed or followed are included, with `status` and the conversion dates set to null.","operationId":"listCreatorTrackingLinkUsers","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","exclusiveMinimum":0,"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"}],"security":[{"BearerAuth":["read:tracking_links","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":["string","null"],"format":"date-time","description":"When the user converted (subscribed to or followed the creator) via this tracking link — the conversion attributed to the link. Despite the name this is not the account-creation date. Reflects the relationship matching the user's current status, and is null when there is no current relationship or when the conversion pre-dates the user's first click on this link (so it was not driven by it). For subscribers the conversion is the start of the subscription currently on file, so a fan who lapsed and resubscribed through this link is attributed to it. For the raw relationship dates regardless of attribution, see subscribedAt / followedAt."},"subscribedAt":{"type":["string","null"],"format":"date-time","description":"When the user first subscribed to the creator, regardless of whether the subscription is attributed to this link. Does not advance when a lapsed fan resubscribes — see currentSubscriptionStartedAt for the start of the subscription currently on file. Null if the user has no subscription to the creator."},"currentSubscriptionStartedAt":{"type":["string","null"],"format":"date-time","description":"When the subscription currently on file began: the most recent resubscribe, or the same value as subscribedAt when the fan never lapsed. Unaffected by renewals. Null if the user has no subscription to the creator."},"followedAt":{"type":["string","null"],"format":"date-time","description":"When the user followed the creator, regardless of whether the follow is attributed to this link. Null if the user does not follow the creator."},"clickedAt":{"type":["string","null"],"format":"date-time","description":"When the user first clicked this tracking link."},"status":{"type":["string","null"],"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","subscribedAt","currentSubscriptionStartedAt","followedAt","clickedAt","status"]},"description":"Users associated with this tracking link"},"nextCursor":{"type":["string","null"],"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","subscribedAt":"2023-11-02T00:00:00.000Z","currentSubscriptionStartedAt":"2024-01-15T00:00:00.000Z","followedAt":null,"clickedAt":"2024-01-14T00: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","subscribedAt":null,"currentSubscriptionStartedAt":null,"followedAt":"2024-01-14T00:00:00.000Z","clickedAt":"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\nMetadata is captured from the query string of the shared short link (`https://www.fanvue.com/<handle>/fv-3?campaign=spring_launch`), using plain query parameters rather than the `metadata[<key>]` syntax checkout links use. Every non-reserved parameter is captured as-is, trimmed to 10 keys and 500 characters per value; over-limit input is silently trimmed rather than rejected.\n\nOnly the most recent impression is returned, and metadata is never merged across clicks: a later click replaces the previous values wholesale, and a later click with no query parameters returns `null`.\n\nReturns 404 when the link is not one of the creator's, and 200 with `metadata: null` when the user has no attributed impression carrying usable metadata.\n\nSee the [tracking links guide](https://api.fanvue.com/docs/tutorials/tracking-links) for the full mechanism, limits and worked examples.","operationId":"getCreatorUserTrackingMetadata","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"}],"security":[{"BearerAuth":["read:tracking_links","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"User's tracking metadata","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom metadata from the user's most recent impression on this link, captured from the query string of the shared short link. Null when the user has no attributed impression carrying usable metadata, including when their latest click carried no query parameters."}},"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.","operationId":"deleteCreatorTrackingLink","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"}],"security":[{"BearerAuth":["write:tracking_links","write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:tracking_links` — Create and delete tracking links.\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"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"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"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>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.fan.presence_changed` webhook event instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/fan-status).\n</Info>","operationId":"getOnlineSubscribers","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":50,"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"}],"security":[{"BearerAuth":["read:creator","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"],"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.","operationId":"createCreatorVaultFolder","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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","null"],"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.","operationId":"listCreatorVaultFolders","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator","read:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"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.","operationId":"getCreatorVaultFolder","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"}],"security":[{"BearerAuth":["read:creator","read:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"responses":{"200":{"description":"Folder details","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Folder name"},"createdAt":{"type":["string","null"],"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.","operationId":"renameCreatorVaultFolder","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"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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.","operationId":"deleteCreatorVaultFolder","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"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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.","operationId":"listCreatorVaultFolderMedia","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"]},"createdAt":{"type":["string","null"],"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","status":"ready","createdAt":"2025-01-15T10:30:00.000Z","caption":null,"description":null,"name":"photo1.jpg","mediaType":"image","recommendedPrice":null,"variants":[{"uuid":"550e8400-e29b-41d4-a716-4466554400aa","variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/550e8400-e29b-41d4-a716-446655440000.jpg","width":1920,"height":1440,"lengthMs":null}]},{"uuid":"550e8400-e29b-41d4-a716-446655440001","status":"processing"}],"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.","operationId":"attachCreatorVaultMedia","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"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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.","operationId":"detachCreatorVaultMedia","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"}],"security":[{"BearerAuth":["write:creator","write:media"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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"}}}},"/creators/{creatorUserUuid}/promotions":{"get":{"summary":"List creator's promotions","description":"List the specified creator's active (non-stopped) subscription promotions.","operationId":"listCreatorPromotions","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of promotions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Promotion UUID"},"type":{"type":"string","enum":["discount","free_trial"],"description":"Whether the promotion is a first-month discount or a free trial"},"discountPercent":{"type":["integer","null"],"description":"Discount percentage (null for free-trial promotions)"},"freeTrialDays":{"type":["integer","null"],"description":"Free trial length in days (null for discount promotions)"},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"endsAt":{"type":["string","null"],"format":"date-time","description":"When the promotion expires (null if it never expires)"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"usedCount":{"type":"integer","description":"Number of times the promotion has been redeemed"},"message":{"type":["string","null"],"description":"Message shown to fans with the promotion"},"createdAt":{"type":"string","format":"date-time","description":"When the promotion was created"}},"required":["uuid","type","discountPercent","freeTrialDays","availableToGroup","endsAt","maxUsages","usedCount","message","createdAt"]},"description":"The creator's active (non-stopped) promotions"}},"required":["data"]},"example":{"data":[{"uuid":"d4e5f6a7-8b9c-4d1e-a2b3-c4d5e6f7a8b9","type":"discount","discountPercent":20,"freeTrialDays":null,"availableToGroup":"new_subscribers","endsAt":"2024-02-15T00:00:00.000Z","maxUsages":100,"usedCount":12,"message":"20% off your first month!","createdAt":"2024-01-15T00:00:00.000Z"},{"uuid":"e5f6a7b8-9c0d-4e2f-b3c4-d5e6f7a8b9c0","type":"free_trial","discountPercent":null,"freeTrialDays":7,"availableToGroup":"followers","endsAt":null,"maxUsages":null,"usedCount":3,"message":null,"createdAt":"2024-01-14T00: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"}}},"post":{"summary":"Create a promotion for a creator","description":"Create a promotional subscription offer on behalf of the specified creator: either a first-month discount (`discountPercent`) or a free trial, never both. For a free trial, set `freeTrialDays` (1-30), or set `freeTrial: true` without `freeTrialDays` for an unlimited (free-forever) trial.\n\nCreating a promotion replaces any existing promotion targeting the same audience group, and eligible fans are notified.","operationId":"createCreatorPromotion","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"discountPercent":{"type":"integer","minimum":1,"maximum":100,"description":"First-month discount as a percentage of the subscription price. Mutually exclusive with a free trial."},"freeTrial":{"type":"boolean","description":"Set to true to offer a free trial. Combine with freeTrialDays for a fixed length, or omit freeTrialDays for an unlimited (free-forever) trial. Mutually exclusive with discountPercent. Passing freeTrialDays alone also implies a free trial."},"freeTrialDays":{"type":"integer","minimum":1,"maximum":30,"description":"Length of the free trial in days (1-30). Omit while freeTrial is true for an unlimited (free-forever) trial. Mutually exclusive with discountPercent."},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"maxUsages":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum number of redemptions. Unlimited when omitted."},"endsAt":{"type":"string","format":"date-time","description":"When the promotion stops being redeemable. Never expires when omitted."},"message":{"type":"string","description":"Optional message shown to fans with the promotion"}},"required":["availableToGroup"]}}}},"responses":{"201":{"description":"Promotion created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Promotion UUID"},"type":{"type":"string","enum":["discount","free_trial"],"description":"Whether the promotion is a first-month discount or a free trial"},"discountPercent":{"type":["integer","null"],"description":"Discount percentage (null for free-trial promotions)"},"freeTrialDays":{"type":["integer","null"],"description":"Free trial length in days (null for discount promotions)"},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"endsAt":{"type":["string","null"],"format":"date-time","description":"When the promotion expires (null if it never expires)"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"usedCount":{"type":"integer","description":"Number of times the promotion has been redeemed"},"message":{"type":["string","null"],"description":"Message shown to fans with the promotion"},"createdAt":{"type":"string","format":"date-time","description":"When the promotion was created"}},"required":["uuid","type","discountPercent","freeTrialDays","availableToGroup","endsAt","maxUsages","usedCount","message","createdAt"]},"example":{"uuid":"d4e5f6a7-8b9c-4d1e-a2b3-c4d5e6f7a8b9","type":"discount","discountPercent":20,"freeTrialDays":null,"availableToGroup":"new_subscribers","endsAt":"2024-02-15T00:00:00.000Z","maxUsages":100,"usedCount":12,"message":"20% off your first month!","createdAt":"2024-01-15T00: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}/promotions/{promotionUuid}":{"put":{"summary":"Edit a creator's promotion","description":"Edit the specified creator's promotion by replacing it, exactly like editing from the dashboard: the referenced promotion is stopped, a new promotion is created with the provided values, and eligible fans are notified of the updated offer.\n\nThe response contains the replacement promotion, whose `uuid` differs from the one in the path and whose `usedCount` starts at zero. Fans who redeemed the original promotion keep their discounted price or trial. If the new values target a different audience group, any existing promotion for that audience is also replaced.","operationId":"updateCreatorPromotion","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Promotion UUID"},"required":true,"description":"Promotion UUID","name":"promotionUuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"discountPercent":{"type":"integer","minimum":1,"maximum":100,"description":"First-month discount as a percentage of the subscription price. Mutually exclusive with a free trial."},"freeTrial":{"type":"boolean","description":"Set to true to offer a free trial. Combine with freeTrialDays for a fixed length, or omit freeTrialDays for an unlimited (free-forever) trial. Mutually exclusive with discountPercent. Passing freeTrialDays alone also implies a free trial."},"freeTrialDays":{"type":"integer","minimum":1,"maximum":30,"description":"Length of the free trial in days (1-30). Omit while freeTrial is true for an unlimited (free-forever) trial. Mutually exclusive with discountPercent."},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"maxUsages":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum number of redemptions. Unlimited when omitted."},"endsAt":{"type":"string","format":"date-time","description":"When the promotion stops being redeemable. Never expires when omitted."},"message":{"type":"string","description":"Optional message shown to fans with the promotion"}},"required":["availableToGroup"]}}}},"responses":{"200":{"description":"Promotion updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Promotion UUID"},"type":{"type":"string","enum":["discount","free_trial"],"description":"Whether the promotion is a first-month discount or a free trial"},"discountPercent":{"type":["integer","null"],"description":"Discount percentage (null for free-trial promotions)"},"freeTrialDays":{"type":["integer","null"],"description":"Free trial length in days (null for discount promotions)"},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"endsAt":{"type":["string","null"],"format":"date-time","description":"When the promotion expires (null if it never expires)"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"usedCount":{"type":"integer","description":"Number of times the promotion has been redeemed"},"message":{"type":["string","null"],"description":"Message shown to fans with the promotion"},"createdAt":{"type":"string","format":"date-time","description":"When the promotion was created"}},"required":["uuid","type","discountPercent","freeTrialDays","availableToGroup","endsAt","maxUsages","usedCount","message","createdAt"]},"example":{"uuid":"d4e5f6a7-8b9c-4d1e-a2b3-c4d5e6f7a8b9","type":"discount","discountPercent":20,"freeTrialDays":null,"availableToGroup":"new_subscribers","endsAt":"2024-02-15T00:00:00.000Z","maxUsages":100,"usedCount":12,"message":"20% off your first month!","createdAt":"2024-01-15T00: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"}}},"delete":{"summary":"Stop a creator's promotion","description":"Stop the specified creator's promotion so it can no longer be redeemed. Fans who already redeemed it keep their discounted price or trial.","operationId":"deleteCreatorPromotion","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Promotion UUID"},"required":true,"description":"Promotion UUID","name":"promotionUuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Promotion stopped 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}/free-trial-links":{"get":{"summary":"List creator's free trial links","description":"List the specified creator's active free trial links, including the shareable URL for each.","operationId":"listCreatorFreeTrialLinks","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of free trial links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Free trial link UUID"},"url":{"type":["string","null"],"description":"Shareable URL fans use to redeem the free trial"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"name":{"type":["string","null"],"description":"Creator-facing label for the link (null when the link is unnamed)"},"usedCount":{"type":"integer","description":"Number of times the link has been redeemed"},"trialDurationDays":{"type":["integer","null"],"description":"Free trial length in days (null when the platform default applies)"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the link expires (null if it never expires)"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","url","maxUsages","name","usedCount","trialDurationDays","expiresAt","createdAt"]},"description":"The creator's active free trial links"}},"required":["data"]},"example":{"data":[{"uuid":"f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","url":"https://www.fanvue.com/creatorhandle?free_trial=f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","maxUsages":50,"name":"Summer promo","usedCount":4,"trialDurationDays":7,"expiresAt":"2024-02-15T00:00:00.000Z","createdAt":"2024-01-15T00:00:00.000Z"},{"uuid":"a7b8c9d0-1e2f-4a3b-c4d5-e6f7a8b9c0d1","url":"https://www.fanvue.com/creatorhandle?free_trial=a7b8c9d0-1e2f-4a3b-c4d5-e6f7a8b9c0d1","maxUsages":null,"name":null,"usedCount":0,"trialDurationDays":null,"expiresAt":null,"createdAt":"2024-01-14T00: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"}}},"post":{"summary":"Create a free trial link for a creator","description":"Create a shareable link on behalf of the specified creator that lets fans start a free trial of their subscription.","operationId":"createCreatorFreeTrialLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"maxUsages":{"type":["integer","null"],"minimum":1,"description":"Maximum number of fans that can redeem the link. Unlimited when null or omitted."},"expiresDays":{"type":["integer","null"],"minimum":1,"description":"Number of days from now until the link expires. Never expires when null or omitted."},"name":{"type":["string","null"],"minLength":1,"maxLength":100,"description":"Creator-facing label used to tell several links apart. Not shown to fans. Unnamed when null or omitted."},"trialDurationDays":{"type":["integer","null"],"minimum":1,"description":"Length of the free trial in days. Uses the platform default when null or omitted."}}}}}},"responses":{"201":{"description":"Free trial link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Free trial link UUID"},"url":{"type":["string","null"],"description":"Shareable URL fans use to redeem the free trial"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"name":{"type":["string","null"],"description":"Creator-facing label for the link (null when the link is unnamed)"},"usedCount":{"type":"integer","description":"Number of times the link has been redeemed"},"trialDurationDays":{"type":["integer","null"],"description":"Free trial length in days (null when the platform default applies)"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the link expires (null if it never expires)"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","url","maxUsages","name","usedCount","trialDurationDays","expiresAt","createdAt"]},"example":{"uuid":"f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","url":"https://www.fanvue.com/creatorhandle?free_trial=f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","maxUsages":50,"name":"Summer promo","usedCount":4,"trialDurationDays":7,"expiresAt":"2024-02-15T00:00:00.000Z","createdAt":"2024-01-15T00: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}/free-trial-links/{uuid}":{"put":{"summary":"Edit a creator's free trial link","description":"Edit the specified creator's free trial link settings. The link keeps its UUID (and shareable URL) and its redemption count; fans already on a trial are unaffected. Omitted fields reset to their unlimited/default state.","operationId":"updateCreatorFreeTrialLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Free trial link UUID"},"required":true,"description":"Free trial link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"maxUsages":{"type":["integer","null"],"minimum":1,"description":"Maximum number of fans that can redeem the link. Unlimited when null or omitted."},"expiresDays":{"type":["integer","null"],"minimum":1,"description":"Number of days from now until the link expires. Never expires when null or omitted."},"name":{"type":["string","null"],"minLength":1,"maxLength":100,"description":"Creator-facing label used to tell several links apart. Not shown to fans. Unnamed when null or omitted."},"trialDurationDays":{"type":["integer","null"],"minimum":1,"description":"Length of the free trial in days. Uses the platform default when null or omitted."}}}}}},"responses":{"200":{"description":"Free trial link updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Free trial link UUID"},"url":{"type":["string","null"],"description":"Shareable URL fans use to redeem the free trial"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"name":{"type":["string","null"],"description":"Creator-facing label for the link (null when the link is unnamed)"},"usedCount":{"type":"integer","description":"Number of times the link has been redeemed"},"trialDurationDays":{"type":["integer","null"],"description":"Free trial length in days (null when the platform default applies)"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the link expires (null if it never expires)"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","url","maxUsages","name","usedCount","trialDurationDays","expiresAt","createdAt"]},"example":{"uuid":"f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","url":"https://www.fanvue.com/creatorhandle?free_trial=f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","maxUsages":50,"name":"Summer promo","usedCount":4,"trialDurationDays":7,"expiresAt":"2024-02-15T00:00:00.000Z","createdAt":"2024-01-15T00: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"}}},"delete":{"summary":"Delete a creator's free trial link","description":"Delete the specified creator's free trial link so it can no longer be redeemed. Fans already on a trial keep it until it ends.","operationId":"deleteCreatorFreeTrialLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Free trial link UUID"},"required":true,"description":"Free trial link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Free trial 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"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/creators/{creatorUserUuid}/subscription-price":{"patch":{"summary":"Update creator's subscription price","description":"Set the specified creator's monthly subscription price, in USD cents (minor units).\n\n**⚠️ Side effect when increasing the price:** all of the creator's existing active subscribers are moved to a pending opt-in state for the new price. With `forceOptIn: false` (default) they keep auto-renewing at their current price until they accept the new one; with `forceOptIn: true` they are forced to opt in at the new price and their current auto-renewal is disabled. The response's `subscribersMovedToReOptIn` reports whether this happened. Decreasing the price has no effect on existing subscribers.\n\nThe new price must stay compatible with the creator's promotions: if any promotion's discount would take it below the platform minimum, the request is rejected until that promotion is deleted.","operationId":"updateCreatorSubscriptionPrice","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionPrice":{"type":"integer","minimum":399,"maximum":10000,"description":"New monthly subscription price in USD cents (minor units), between 399 and 10000"},"forceOptIn":{"type":"boolean","default":false,"description":"Only used when the price increases. When false (default), existing subscribers keep auto-renewing at their current price until they opt in to the new one. When true, they are forced to opt in at the new price and their current auto-renewal is disabled."}},"required":["subscriptionPrice"]}}}},"responses":{"200":{"description":"Subscription price updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionPrice":{"type":"integer","description":"The subscription price now in effect, in USD cents (minor units)"},"subscribersMovedToReOptIn":{"type":"boolean","description":"True when the price increase moved existing active subscribers to a pending re-opt-in state (see the endpoint description)"}},"required":["subscriptionPrice","subscribersMovedToReOptIn"]},"example":{"subscriptionPrice":999,"subscribersMovedToReOptIn":true}}}},"400":{"description":"Invalid price, not a creator account, or conflicting active promotion","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"}}}},"/creators/{creatorUserUuid}/chats/automated-messages":{"get":{"summary":"List a creator's automated messages","description":"Returns the per-trigger state of the specified creator's automated messages. All triggers are always listed; disabled triggers have `enabled: false` and null content fields.","operationId":"listCreatorAutomatedMessages","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Per-trigger automated message state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"trigger":{"type":"string","enum":["new_subscriber","new_follower","subscription_canceled","re_subscribed","renewed","new_purchase","first_message_reply"],"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)"},"enabled":{"type":"boolean","description":"Whether an automated message is active for this trigger"},"text":{"type":["string","null"],"description":"Message text content (null when disabled or media-only)"},"price":{"type":["number","null"],"description":"Pay-to-view price in cents (null when disabled or unpriced)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ordered list of media UUIDs attached to the message (empty when disabled)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the free preview media, or null when none is set"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the automated message was last configured (null when disabled)"}},"required":["trigger","enabled","text","price","mediaUuids","mediaPreviewUuid","updatedAt"]},"description":"Per-trigger state for all automated message triggers"}},"required":["data"]},"example":{"data":[{"trigger":"new_subscriber","enabled":true,"text":"Hey! Thanks for subscribing! Check out my latest exclusive content 🔥","price":999,"mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"mediaPreviewUuid":"8d9e6679-7425-40de-944b-e07fc1f90ae8","updatedAt":"2026-07-01T12:00:00.000Z"},{"trigger":"new_follower","enabled":true,"text":"Thanks for the follow! 💝","price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":"2026-06-15T09:30:00.000Z"},{"trigger":"subscription_canceled","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":null},{"trigger":"re_subscribed","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":null},{"trigger":"renewed","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":null},{"trigger":"new_purchase","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"updatedAt":null},{"trigger":"first_message_reply","enabled":false,"text":null,"price":null,"mediaUuids":[],"mediaPreviewUuid":null,"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"}}}},"/creators/{creatorUserUuid}/chats/automated-messages/{trigger}":{"put":{"summary":"Enable or update a creator's automated message","description":"Creates or replaces the automated message sent on behalf of the specified creator when the trigger fires. The message must have text or media; a non-zero price requires media.","operationId":"upsertCreatorAutomatedMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","enum":["new_subscriber","new_follower","subscription_canceled","re_subscribed","renewed","new_purchase","first_message_reply"],"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)"},"required":true,"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)","name":"trigger","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":5000,"description":"Message text content"},"price":{"anyOf":[{"type":"number","enum":[0]},{"type":"integer","minimum":300,"maximum":250000}],"description":"Pay-to-view price in cents: 0 (free) or between 300 and 250000. A non-zero price requires attached media."},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of media UUIDs to attach to the message"},"mediaPreviewUuid":{"type":"string","format":"uuid","description":"UUID of a single media item shown for free as a preview of a pay-to-view message. Requires a price and attached media."}}}}}},"responses":{"200":{"description":"Automated message enabled or updated","content":{"application/json":{"schema":{"type":"object","properties":{"trigger":{"type":"string","enum":["new_subscriber","new_follower","subscription_canceled","re_subscribed","renewed","new_purchase","first_message_reply"],"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)"},"enabled":{"type":"boolean","description":"Whether an automated message is active for this trigger"},"text":{"type":["string","null"],"description":"Message text content (null when disabled or media-only)"},"price":{"type":["number","null"],"description":"Pay-to-view price in cents (null when disabled or unpriced)"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ordered list of media UUIDs attached to the message (empty when disabled)"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of the free preview media, or null when none is set"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the automated message was last configured (null when disabled)"}},"required":["trigger","enabled","text","price","mediaUuids","mediaPreviewUuid","updatedAt"]},"example":{"trigger":"new_subscriber","enabled":true,"text":"Hey! Thanks for subscribing! Check out my latest exclusive content 🔥","price":999,"mediaUuids":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"mediaPreviewUuid":"8d9e6679-7425-40de-944b-e07fc1f90ae8","updatedAt":"2026-07-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"}}},"delete":{"summary":"Disable a creator's automated message","description":"Disables the specified creator's automated message for the trigger. Returns 404 if the trigger is not currently enabled.","operationId":"deleteCreatorAutomatedMessage","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"string","enum":["new_subscriber","new_follower","subscription_canceled","re_subscribed","renewed","new_purchase","first_message_reply"],"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)"},"required":true,"description":"Event that sends the automated message: new_subscriber, new_follower, subscription_canceled (subscriber cancels auto-renew), re_subscribed, renewed (subscription renews), new_purchase, or first_message_reply (fan messages the creator for the first time)","name":"trigger","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Automated message disabled"},"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":"Automated 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/{creatorUserUuid}/account-health":{"get":{"summary":"Get a creator's account health","description":"Get the specified creator's account health summary: total warnings issued against the account and how many media items moderation has removed or is currently reviewing.\n\nThis is confidential moderation data and only ever reflects the specified creator's own account.","operationId":"getCreatorAccountHealth","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"Account health summary","content":{"application/json":{"schema":{"type":"object","properties":{"totalWarnings":{"type":"integer","description":"Total number of warnings issued against the creator's account"},"totalRemovedMedia":{"type":"integer","description":"Total number of the creator's media items removed by moderation"},"totalInReviewMedia":{"type":"integer","description":"Total number of the creator's media items currently under moderation review"}},"required":["totalWarnings","totalRemovedMedia","totalInReviewMedia"]},"example":{"totalWarnings":2,"totalRemovedMedia":1,"totalInReviewMedia":3}}}},"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}/account-health/flagged-media":{"get":{"summary":"List a creator's flagged media","description":"List the specified creator's media items flagged by moderation, most recent first: media removed by moderation and media currently under review. Use the `status` query parameter to narrow to one of the two.\n\nOnly moderation metadata is returned, never the media content itself. This is confidential moderation data and only ever reflects the specified creator's own media.","operationId":"listCreatorFlaggedMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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":["in_review","removed"],"description":"Filter to media with this moderation status. Returns both in_review and removed media when omitted."},"required":false,"description":"Filter to media with this moderation status. Returns both in_review and removed media when omitted.","name":"status","in":"query"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of flagged media","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Media UUID"},"mediaType":{"type":"string","enum":["image","video","audio","document","unknown"]},"moderationStatus":{"type":"string","enum":["in_review","removed"],"description":"Moderation status of the media: in_review (awaiting a moderation decision) or removed (taken down by moderation)"},"createdAt":{"type":"string","format":"date-time","description":"When the media was uploaded"}},"required":["uuid","mediaType","moderationStatus","createdAt"]},"description":"The creator's flagged media items, most recent first"},"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-4a7b-8c9d-0e1f2a3b4c5d","mediaType":"video","moderationStatus":"in_review","createdAt":"2024-02-12T18:45:00.000Z"},{"uuid":"b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e","mediaType":"image","moderationStatus":"removed","createdAt":"2024-01-20T11:15: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}/blocks/{userUuid}":{"post":{"summary":"Block a user on behalf of a creator","description":"Block a user on behalf of the specified creator.\n\n**Blocking a fan auto-cancels their subscription.** When the blocked user is a subscriber, this endpoint cancels their active subscription to the creator (cancellation reason `creator_blocked`) as part of the block. It also marks the conversation with the blocked user as read. These are existing platform side effects of a block, applied here for parity with the Fanvue app.\n\nReturns 404 if the target user does not exist.","operationId":"blockCreatorUser","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 user to block or unblock"},"required":true,"description":"UUID of the user to block or unblock","name":"userUuid","in":"path"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"204":{"description":"User blocked 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"}}},"delete":{"summary":"Unblock a user on behalf of a creator","description":"Remove a block on behalf of the specified creator. Unblocking does not restore a subscription that was cancelled when the user was blocked. No-ops if the user is not currently blocked. Returns 404 if the target user does not exist.","operationId":"unblockCreatorUser","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 user to block or unblock"},"required":true,"description":"UUID of the user to block or unblock","name":"userUuid","in":"path"}],"security":[{"BearerAuth":["write:chat","read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `write:chat` — Create new chats and send messages. This scope is required for any chat-related actions that modify data.\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"204":{"description":"User unblocked 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}/blocks":{"get":{"summary":"List users blocked by a creator","description":"List the users the specified creator has blocked, most recently registered first. Supports pagination.","operationId":"listCreatorBlockedUsers","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"creatorUserUuid","in":"path"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:creator","read:chat","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n  - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"responses":{"200":{"description":"List of blocked users","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID of the blocked user"},"handle":{"type":"string","description":"Handle of the blocked user"},"displayName":{"type":"string","description":"Display name of the blocked user"},"avatarUrl":{"type":["string","null"],"description":"Avatar URL of the blocked user, or null if none"}},"required":["uuid","handle","displayName","avatarUrl"]},"description":"Users the creator has blocked"},"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":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","handle":"blockeduser","displayName":"Blocked User","avatarUrl":"https://cdn.fanvue.com/avatars/b3f1c2d4.jpg"}],"pagination":{"page":1,"size":1,"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"}}}},"/experiences/token/exchange":{"post":{"summary":"Exchange a fan experience launch token","description":"Exchanges the opaque experience token an app's fan-experience surface received in its iframe URL for the resolved experience, the fan's identity, and the fan's entitlement to the experience.\n\n    The token is bound to the app that owns the experience: a token minted for one app cannot be exchanged with another app's credentials (403).\n\n    Returns 400 if the token is invalid or expired, and 404 if the experience no longer exists.","operationId":"exchangeExperienceToken","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:experience"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:experience` — Exchange a fan's experience token for the resolved experience and the fan's identity, so an embedded fan-facing experience can render the right content.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":1,"description":"The opaque experience launch token appended to the surface iframe URL.","example":"exp_2f1c…"}},"required":["token"]}}}},"responses":{"200":{"description":"The resolved experience, fan identity, and entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"experience":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"appUuid":{"type":"string","format":"uuid"},"creatorUuid":{"type":"string","format":"uuid"},"externalExperienceId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"accessMode":{"type":"string","enum":["FREE","SUBSCRIPTION","PAID","HIDDEN"]},"hidden":{"type":"boolean"}},"required":["uuid","appUuid","creatorUuid","externalExperienceId","title","description","accessMode","hidden"]},"fanUuid":{"type":"string","format":"uuid"},"entitlement":{"type":"object","properties":{"isEntitled":{"type":"boolean"},"mode":{"type":"string","enum":["FREE","SUBSCRIPTION","PAID","HIDDEN"]},"reason":{"type":"string"}},"required":["isEntitled","mode","reason"]}},"required":["experience","fanUuid","entitlement"]},"example":{"experience":{"uuid":"00000000-0000-4000-8000-000000000010","appUuid":"00000000-0000-4000-8000-000000000001","creatorUuid":"00000000-0000-4000-8000-000000000002","externalExperienceId":"ext-experience-123","title":"Behind the scenes","description":"An exclusive behind-the-scenes experience.","accessMode":"SUBSCRIPTION","hidden":false},"fanUuid":"00000000-0000-4000-8000-000000000003","entitlement":{"isEntitled":true,"mode":"SUBSCRIPTION","reason":"subscribed"}}}}},"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":{"description":"Experience not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"},"502":{"description":"Failed to exchange the experience token with the 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"}}}}}}}}},"/experiences/request-token":{"post":{"summary":"Mint a publish/unpublish request token","description":"Mints a short-lived, opaque \"request token\" the app's creator surface forwards to Fanvue to ask the creator to confirm a publish or unpublish.\n\n    The token is bound to the calling app (a token can only be minted for the app whose credentials make the call — otherwise 403) and to the acting creator, so it can only drive that creator's native confirmation modal.","operationId":"mintExperienceRequestToken","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:experience"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:experience` — Request that the creator publish or unpublish a fan-facing experience. The app mints a request token; the creator confirms and Fanvue performs the change.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","enum":["publish"]},"externalExperienceId":{"type":"string","minLength":1},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":["string","null"],"maxLength":2048,"format":"uri","description":"Public https URL of the experience cover image. Fanvue downloads and re-hosts it when the creator confirms the publish.","example":"https://example.com/covers/launch-your-page.jpg"},"proposedAccessMode":{"type":"string","enum":["FREE","SUBSCRIPTION","PAID","HIDDEN"]},"deliveryMode":{"type":"string","enum":["EMBEDDED","EXTERNAL"]},"externalUrl":{"type":["string","null"]},"appUuid":{"type":"string","format":"uuid"}},"required":["action","externalExperienceId","title","description","proposedAccessMode","deliveryMode","appUuid"]},{"type":"object","properties":{"action":{"type":"string","enum":["unpublish"]},"experienceUuid":{"type":"string","format":"uuid"},"title":{"type":"string"},"appUuid":{"type":"string","format":"uuid"}},"required":["action","experienceUuid","title","appUuid"]}]}}}},"responses":{"200":{"description":"The minted request token","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The opaque request token to forward to the creator surface for confirmation.","example":"req_2f1c…"}},"required":["token"]}}}},"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"},"502":{"description":"Failed to mint the request token with the 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"}}}}}}}}},"/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>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.follow.created` webhook event instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/engagement).\n</Info>","operationId":"listFollowers","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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"}}}},"/free-trial-links":{"get":{"summary":"List free trial links","description":"List the authenticated creator's active free trial links, including the shareable URL for each.","operationId":"listFreeTrialLinks","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of free trial links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Free trial link UUID"},"url":{"type":["string","null"],"description":"Shareable URL fans use to redeem the free trial"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"name":{"type":["string","null"],"description":"Creator-facing label for the link (null when the link is unnamed)"},"usedCount":{"type":"integer","description":"Number of times the link has been redeemed"},"trialDurationDays":{"type":["integer","null"],"description":"Free trial length in days (null when the platform default applies)"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the link expires (null if it never expires)"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","url","maxUsages","name","usedCount","trialDurationDays","expiresAt","createdAt"]},"description":"The creator's active free trial links"}},"required":["data"]},"example":{"data":[{"uuid":"f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","url":"https://www.fanvue.com/creatorhandle?free_trial=f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","maxUsages":50,"name":"Summer promo","usedCount":4,"trialDurationDays":7,"expiresAt":"2024-02-15T00:00:00.000Z","createdAt":"2024-01-15T00:00:00.000Z"},{"uuid":"a7b8c9d0-1e2f-4a3b-c4d5-e6f7a8b9c0d1","url":"https://www.fanvue.com/creatorhandle?free_trial=a7b8c9d0-1e2f-4a3b-c4d5-e6f7a8b9c0d1","maxUsages":null,"name":null,"usedCount":0,"trialDurationDays":null,"expiresAt":null,"createdAt":"2024-01-14T00:00:00.000Z"}]}}}},"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 free trial link","description":"Create a shareable link that lets fans start a free trial of the creator's subscription.","operationId":"createFreeTrialLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"maxUsages":{"type":["integer","null"],"minimum":1,"description":"Maximum number of fans that can redeem the link. Unlimited when null or omitted."},"expiresDays":{"type":["integer","null"],"minimum":1,"description":"Number of days from now until the link expires. Never expires when null or omitted."},"name":{"type":["string","null"],"minLength":1,"maxLength":100,"description":"Creator-facing label used to tell several links apart. Not shown to fans. Unnamed when null or omitted."},"trialDurationDays":{"type":["integer","null"],"minimum":1,"description":"Length of the free trial in days. Uses the platform default when null or omitted."}}}}}},"responses":{"201":{"description":"Free trial link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Free trial link UUID"},"url":{"type":["string","null"],"description":"Shareable URL fans use to redeem the free trial"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"name":{"type":["string","null"],"description":"Creator-facing label for the link (null when the link is unnamed)"},"usedCount":{"type":"integer","description":"Number of times the link has been redeemed"},"trialDurationDays":{"type":["integer","null"],"description":"Free trial length in days (null when the platform default applies)"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the link expires (null if it never expires)"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","url","maxUsages","name","usedCount","trialDurationDays","expiresAt","createdAt"]},"example":{"uuid":"f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","url":"https://www.fanvue.com/creatorhandle?free_trial=f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","maxUsages":50,"name":"Summer promo","usedCount":4,"trialDurationDays":7,"expiresAt":"2024-02-15T00:00:00.000Z","createdAt":"2024-01-15T00:00:00.000Z"}}}},"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"}}}},"/free-trial-links/{uuid}":{"put":{"summary":"Edit a free trial link","description":"Edit an existing free trial link's settings. The link keeps its UUID (and shareable URL) and its redemption count; fans already on a trial are unaffected. Omitted fields reset to their unlimited/default state.","operationId":"updateFreeTrialLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Free trial link UUID"},"required":true,"description":"Free trial link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"maxUsages":{"type":["integer","null"],"minimum":1,"description":"Maximum number of fans that can redeem the link. Unlimited when null or omitted."},"expiresDays":{"type":["integer","null"],"minimum":1,"description":"Number of days from now until the link expires. Never expires when null or omitted."},"name":{"type":["string","null"],"minLength":1,"maxLength":100,"description":"Creator-facing label used to tell several links apart. Not shown to fans. Unnamed when null or omitted."},"trialDurationDays":{"type":["integer","null"],"minimum":1,"description":"Length of the free trial in days. Uses the platform default when null or omitted."}}}}}},"responses":{"200":{"description":"Free trial link updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Free trial link UUID"},"url":{"type":["string","null"],"description":"Shareable URL fans use to redeem the free trial"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"name":{"type":["string","null"],"description":"Creator-facing label for the link (null when the link is unnamed)"},"usedCount":{"type":"integer","description":"Number of times the link has been redeemed"},"trialDurationDays":{"type":["integer","null"],"description":"Free trial length in days (null when the platform default applies)"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the link expires (null if it never expires)"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","url","maxUsages","name","usedCount","trialDurationDays","expiresAt","createdAt"]},"example":{"uuid":"f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","url":"https://www.fanvue.com/creatorhandle?free_trial=f6a7b8c9-0d1e-4f2a-b3c4-d5e6f7a8b9c0","maxUsages":50,"name":"Summer promo","usedCount":4,"trialDurationDays":7,"expiresAt":"2024-02-15T00:00:00.000Z","createdAt":"2024-01-15T00: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"}}},"delete":{"summary":"Delete a free trial link","description":"Delete a free trial link so it can no longer be redeemed. Fans already on a trial keep it until it ends.","operationId":"deleteFreeTrialLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Free trial link UUID"},"required":true,"description":"Free trial link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Free trial 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"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"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. Reversals are included as `refund`/`chargeback` rows with negative gross (matching /insights/spending); filter them with `source`.\n\nPass `transactionOrderIds` (comma-separated, max 100) to fetch only specific transactions by ID — useful for re-fetching known transactions to pick up status changes. It combines with the other filters and normal pagination still applies.\n\n<Info>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.payment.succeeded`, `creator.refund.created`, `creator.dispute.created`, `creator.dispute.flagged` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/payments).\n</Info>\n\nWebhooks replace polling for _detecting_ these events, but for authoritative financial figures you should still reconcile against this endpoint. The `creator.payment.succeeded` payload's `data.id` is the Fanvue invoice number, which matches the `transactionOrderId` on the rows returned here — pass it to `transactionOrderIds` to cross-check specific transactions without a full re-poll.","operationId":"getEarnings","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":"array","items":{"type":"string"},"description":"Comma-separated transaction order IDs (max 100)"},"required":false,"description":"Comma-separated transaction order IDs to fetch (max 100). Use to re-fetch specific transactions by ID and pick up status changes. Combines with the other filters; normal pagination still applies.","name":"transactionOrderIds","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,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused."},"required":false,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.","name":"size","in":"query"}],"security":[{"BearerAuth":["read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"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","null"],"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"},"reversedTransactionOrderId":{"type":"string","description":"Only on `refund` and `chargeback` rows: the `transactionOrderId` of the original transaction this row reverses. A reversal never rewrites the original transaction, so use this to link the two."},"messageUuid":{"type":"string","format":"uuid","description":"Message UUID when source is message (e.g. paid chat or broadcast message). Also present on tip rows, where it identifies the chat message Fanvue writes into the thread to record the tip — including for tips sent on a post. On a tip it is therefore not a signal that the tip came from a chat; use `tipContext` and `postUuid` for that."},"messageType":{"type":"string","enum":["AUTOMATED_CANCELED","AUTOMATED_NEW_FOLLOWER","AUTOMATED_NEW_PURCHASE","AUTOMATED_NEW_SUBSCRIBER","AUTOMATED_RE_SUBSCRIBED","AUTOMATED_RENEWED","AUTOMATED_FIRST_MESSAGE_REPLY","AUTOMATED_CHAT_MESSAGE_REPLY","BROADCAST","CHAT_TEXT_GENERATION","CHAT_TEXT_REWRITE","CHAT_TEXT_REPLY","GHOST_PROMOTION","MARKETING_KYC","TIP","LOCKED_MESSAGE_UNLOCKED","VOICE_CALL","SINGLE_RECIPIENT"],"description":"Underlying chat message type when source is message. Same values as the `type` field on the messages API — e.g. SINGLE_RECIPIENT (1-to-1 DM), BROADCAST / GHOST_PROMOTION (mass message), AUTOMATED_* (automated message). Use it to distinguish direct, mass, and automated message earnings."},"postUuid":{"type":"string","format":"uuid","description":"Post UUID when source is post"},"tipContext":{"type":"string","enum":["post","message"],"description":"Context of a tip when source is tip. `post` when the tip was sent on a post — `postUuid` identifies which. `message` for every other tip. Read `message` as 'not on a post' rather than 'in a chat': there is deliberately no `profile` value, because Fanvue does not record which surface a fan tipped from, so a tip sent in a chat thread and a tip sent from a creator profile are indistinguishable and both report `message`. Do not treat `message` as evidence of a chat origin when attributing revenue. Buckets identically to the `context` field on the tip.new webhook."},"user":{"type":["object","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"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","null"],"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","tipContext":"message","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"}},{"date":"2024-01-14T00:00:00.000Z","gross":2500,"net":2125,"currency":"USD","source":"message","transactionOrderId":"FV-ORDER-126","transactionOrderStatus":"availableForPayout","messageUuid":"b7c8d9e0-1234-5678-9abc-def012345678","messageType":"BROADCAST","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":"refund","transactionOrderId":"FV-ORDER-125","transactionOrderStatus":"availableForPayout","reversedTransactionOrderId":"FV-ORDER-124","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.","operationId":"getEarningsSummary","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"}],"security":[{"BearerAuth":["read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"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","null"]},"netChangePercentage":{"type":["number","null"]}},"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","null"]},"endDate":{"type":["string","null"]},"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/earnings/percentile":{"get":{"summary":"Get earnings percentile","description":"Returns the earnings percentile bucket the authenticated creator falls into based on their gross earnings over the last 30 days.\n\nThe value is a decimal percentile where lower numbers indicate higher rank (e.g. `0.01` means top 0.01% of earners, `99.50` is near the bottom). Buckets are derived from a periodic snapshot of platform-wide earnings, not a live recomputation, and may take any decimal value the snapshot exposes — not just whole numbers.","operationId":"getEarningsPercentile","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"responses":{"200":{"description":"Earnings percentile for the authenticated creator","content":{"application/json":{"schema":{"type":"object","properties":{"percentile":{"type":"number","description":"Earnings percentile (decimal) the creator falls into based on their gross earnings over the last 30 days. Lower values indicate higher rank: 0.01 = top 0.01% of earners, 99.50 ≈ bottom. Values are not constrained to whole numbers — bucket granularity is determined by the lookup table."}},"required":["percentile"]},"example":{"percentile":12.5}}}},"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/fan-retention-summary":{"get":{"summary":"Get fan retention summary","description":"Returns the authenticated creator's weekly fan-health snapshots, including paid/free active fans, churn, retention, reactivation, revenue retention, LTV, free-to-paid conversion, and engagement metrics. Snapshots are computed weekly by the data warehouse (not real-time); the most recent snapshot may be up to 7 days old.","operationId":"getFanRetentionSummary","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","minimum":1,"maximum":12,"default":6,"description":"Number of most-recent weekly snapshots to return (1-12, default: 6)"},"required":false,"description":"Number of most-recent weekly snapshots to return (1-12, default: 6)","name":"periods","in":"query"}],"security":[{"BearerAuth":["read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"responses":{"200":{"description":"Weekly fan retention snapshots","content":{"application/json":{"schema":{"type":"object","properties":{"snapshots":{"type":"array","items":{"type":"object","properties":{"periodStart":{"type":"string","format":"date-time","description":"Start of the weekly snapshot period as a UTC ISO 8601 datetime string"},"paidActiveFansCount":{"type":"number","description":"Paid (subscribed) active fans at the end of the week"},"prevPaidActiveFansCount":{"type":"number","description":"Paid active fans in the previous week"},"paidChurnedFansCount":{"type":"number","description":"Paid fans who churned during the week"},"paidRetainedFansCount":{"type":"number","description":"Paid fans retained from the previous week"},"paidNewFansCount":{"type":"number","description":"Net-new paid fans gained during the week"},"paidReactivatedFansCount":{"type":"number","description":"Previously churned paid fans who returned"},"paidFanChurnRate":{"type":"number","description":"Paid fan churn rate for the week (0-1)"},"paidFanNrr":{"type":"number","description":"Net revenue retention for paid fans"},"paidReactivationRate":{"type":"number","description":"Paid fan reactivation rate for the week"},"revenueCurrent":{"type":"number","description":"Subscription revenue this week, in USD cents"},"revenuePrevious":{"type":"number","description":"Subscription revenue the previous week, in USD cents"},"revenueRetained":{"type":"number","description":"Revenue from retained fans, in USD cents"},"revenueLost":{"type":"number","description":"Revenue lost to churn, in USD cents"},"revenueNewFans":{"type":"number","description":"Revenue from new fans, in USD cents"},"revenueReactivatedFans":{"type":"number","description":"Revenue from reactivated fans, in USD cents"},"ltvSimple":{"type":"number","description":"Simple lifetime value estimate, in USD cents"},"ltvWeighted":{"type":"number","description":"Churn-weighted lifetime value estimate, in USD cents"},"totalUniqueFans":{"type":"number","description":"Total unique fans (paid + free)"},"freeActiveFansCount":{"type":"number","description":"Free active fans at the end of the week"},"freeRetainedFansCount":{"type":"number","description":"Free fans retained from the previous week"},"freeNewFansCount":{"type":"number","description":"Net-new free fans gained during the week"},"freeReactivatedFansCount":{"type":"number","description":"Previously churned free fans who returned"},"freeChurnedFansCount":{"type":"number","description":"Free fans who churned during the week"},"freeFanChurnRate":{"type":"number","description":"Free fan churn rate for the week (0-1)"},"freeToPaidConversionCount":{"type":"number","description":"Free fans who converted to paid during the week"},"totalActiveFansCount":{"type":"number","description":"Total active fans (paid + free)"},"weeklyPostCount":{"type":"number","description":"Posts published during the week"},"weeklyPostingDays":{"type":"number","description":"Distinct days the creator posted"},"weeklySubscriberOnlyPosts":{"type":"number","description":"Subscriber-only posts published"},"weeklyFreePosts":{"type":"number","description":"Free posts published"},"weeklyPpvPosts":{"type":"number","description":"Pay-per-view posts published"},"weeklyAvgMediaPerPost":{"type":"number","description":"Average media attachments per post"},"weeklyPctPostsWithMedia":{"type":"number","description":"Share of posts containing media (0-1)"},"weeklyAvgLikesPerPost":{"type":"number","description":"Average likes per post"},"weeklyAvgCommentsPerPost":{"type":"number","description":"Average comments per post"},"weeklySingleMessagesSent":{"type":"number","description":"One-to-one messages sent"},"weeklyBroadcastMessagesSent":{"type":"number","description":"Broadcast/mass messages sent"},"weeklyUniqueFansMessaged":{"type":"number","description":"Unique fans messaged"},"weeklyAvgResponseTimeHours":{"type":"number","description":"Average response time to fans, in hours"},"weeklyPctRespondedWithin1h":{"type":"number","description":"Share of fan messages answered within 1h (0-1)"},"weeklyPctRespondedWithin4h":{"type":"number","description":"Share of fan messages answered within 4h (0-1)"},"weeklyPctRespondedWithin12h":{"type":"number","description":"Share of fan messages answered within 12h (0-1)"},"weeklyFansRespondedCount":{"type":"number","description":"Fans the creator responded to"},"weeklyFanResponseRate":{"type":"number","description":"Share of fans responded to (0-1)"}},"required":["periodStart","paidActiveFansCount","prevPaidActiveFansCount","paidChurnedFansCount","paidRetainedFansCount","paidNewFansCount","paidReactivatedFansCount","paidFanChurnRate","paidFanNrr","paidReactivationRate","revenueCurrent","revenuePrevious","revenueRetained","revenueLost","revenueNewFans","revenueReactivatedFans","ltvSimple","ltvWeighted","totalUniqueFans","freeActiveFansCount","freeRetainedFansCount","freeNewFansCount","freeReactivatedFansCount","freeChurnedFansCount","freeFanChurnRate","freeToPaidConversionCount","totalActiveFansCount","weeklyPostCount","weeklyPostingDays","weeklySubscriberOnlyPosts","weeklyFreePosts","weeklyPpvPosts","weeklyAvgMediaPerPost","weeklyPctPostsWithMedia","weeklyAvgLikesPerPost","weeklyAvgCommentsPerPost","weeklySingleMessagesSent","weeklyBroadcastMessagesSent","weeklyUniqueFansMessaged","weeklyAvgResponseTimeHours","weeklyPctRespondedWithin1h","weeklyPctRespondedWithin4h","weeklyPctRespondedWithin12h","weeklyFansRespondedCount","weeklyFanResponseRate"]},"description":"Weekly fan-health snapshots, most recent first"}},"required":["snapshots"]},"example":{"snapshots":[{"periodStart":"2026-03-16T00:00:00.000Z","paidActiveFansCount":1240,"prevPaidActiveFansCount":1180,"paidChurnedFansCount":95,"paidRetainedFansCount":1085,"paidNewFansCount":120,"paidReactivatedFansCount":35,"paidFanChurnRate":0.08,"paidFanNrr":1.04,"paidReactivationRate":0.03,"revenueCurrent":1860000,"revenuePrevious":1770000,"revenueRetained":1627500,"revenueLost":142500,"revenueNewFans":180000,"revenueReactivatedFans":52500,"ltvSimple":18750,"ltvWeighted":21300,"totalUniqueFans":4820,"freeActiveFansCount":3580,"freeRetainedFansCount":3210,"freeNewFansCount":410,"freeReactivatedFansCount":60,"freeChurnedFansCount":300,"freeFanChurnRate":0.08,"freeToPaidConversionCount":48,"totalActiveFansCount":4820,"weeklyPostCount":9,"weeklyPostingDays":5,"weeklySubscriberOnlyPosts":4,"weeklyFreePosts":3,"weeklyPpvPosts":2,"weeklyAvgMediaPerPost":2.4,"weeklyPctPostsWithMedia":0.89,"weeklyAvgLikesPerPost":156,"weeklyAvgCommentsPerPost":23,"weeklySingleMessagesSent":540,"weeklyBroadcastMessagesSent":3,"weeklyUniqueFansMessaged":310,"weeklyAvgResponseTimeHours":1.6,"weeklyPctRespondedWithin1h":0.62,"weeklyPctRespondedWithin4h":0.85,"weeklyPctRespondedWithin12h":0.95,"weeklyFansRespondedCount":290,"weeklyFanResponseRate":0.94},{"periodStart":"2026-03-09T00:00:00.000Z","paidActiveFansCount":1180,"prevPaidActiveFansCount":1150,"paidChurnedFansCount":88,"paidRetainedFansCount":1062,"paidNewFansCount":90,"paidReactivatedFansCount":28,"paidFanChurnRate":0.077,"paidFanNrr":1.02,"paidReactivationRate":0.024,"revenueCurrent":1770000,"revenuePrevious":1725000,"revenueRetained":1593000,"revenueLost":132000,"revenueNewFans":135000,"revenueReactivatedFans":42000,"ltvSimple":18200,"ltvWeighted":20600,"totalUniqueFans":4710,"freeActiveFansCount":3470,"freeRetainedFansCount":3160,"freeNewFansCount":360,"freeReactivatedFansCount":50,"freeChurnedFansCount":310,"freeFanChurnRate":0.082,"freeToPaidConversionCount":41,"totalActiveFansCount":4710,"weeklyPostCount":7,"weeklyPostingDays":4,"weeklySubscriberOnlyPosts":3,"weeklyFreePosts":3,"weeklyPpvPosts":1,"weeklyAvgMediaPerPost":2.1,"weeklyPctPostsWithMedia":0.86,"weeklyAvgLikesPerPost":142,"weeklyAvgCommentsPerPost":19,"weeklySingleMessagesSent":505,"weeklyBroadcastMessagesSent":2,"weeklyUniqueFansMessaged":295,"weeklyAvgResponseTimeHours":1.9,"weeklyPctRespondedWithin1h":0.58,"weeklyPctRespondedWithin4h":0.82,"weeklyPctRespondedWithin12h":0.93,"weeklyFansRespondedCount":276,"weeklyFanResponseRate":0.92}]}}}},"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/unsubscribe-reasons":{"get":{"summary":"Get unsubscribe reasons","description":"Returns a breakdown of why fans are unsubscribing from the authenticated creator, based on exit-survey data.\n\nThis is the same fan-health data surfaced in the Creator Agent. It is aggregated weekly (not real-time): `currentWeekCount` covers the most recent snapshot period and `rollingCount` spans the last 12 weeks. Frame it as \"based on the last 12 weeks of exit surveys\" rather than live data.\n\nReasons returned: `too_expensive`, `not_enough_content`, `content_not_expected`, `creator_not_active`, and `other`. The `*Total` fields count all surveys in the window and may exceed the sum of the listed reasons.","operationId":"getUnsubscribeReasons","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"date-time","description":"ISO 8601 datetime anchoring the current-week window. Counts are aggregated on weekly fan-health snapshots, so this is snapped to the snapshot boundary. If omitted, defaults to the most recent snapshot period."},"required":false,"description":"ISO 8601 datetime anchoring the current-week window. Counts are aggregated on weekly fan-health snapshots, so this is snapped to the snapshot boundary. If omitted, defaults to the most recent snapshot period.","name":"periodStart","in":"query"}],"security":[{"BearerAuth":["read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"responses":{"200":{"description":"Unsubscribe reasons breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"reasons":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","description":"Exit-survey reason. One of: too_expensive, not_enough_content, content_not_expected, creator_not_active, other."},"currentWeekCount":{"type":"integer","description":"Number of fans citing this reason in the most recent snapshot week"},"rollingCount":{"type":"integer","description":"Number of fans citing this reason across the last 12 weeks"}},"required":["reason","currentWeekCount","rollingCount"]},"description":"Per-reason counts. Based on exit surveys, aggregated weekly — not real-time."},"currentWeekTotal":{"type":"integer","description":"Total exit surveys in the most recent snapshot week (across all reasons)"},"rollingTotal":{"type":"integer","description":"Total exit surveys across the last 12 weeks (across all reasons)"}},"required":["reasons","currentWeekTotal","rollingTotal"]},"example":{"reasons":[{"reason":"too_expensive","currentWeekCount":3,"rollingCount":28},{"reason":"not_enough_content","currentWeekCount":2,"rollingCount":19},{"reason":"content_not_expected","currentWeekCount":1,"rollingCount":11},{"reason":"creator_not_active","currentWeekCount":0,"rollingCount":6},{"reason":"other","currentWeekCount":1,"rollingCount":9}],"currentWeekTotal":7,"rollingTotal":73}}}},"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. Pass `fanUuid` to restrict results to a single fan's reversals on this creator.","operationId":"getSpending","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,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused."},"required":false,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.","name":"size","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Restrict results to reversals belonging to a single fan on this creator"},"required":false,"description":"Restrict results to reversals belonging to a single fan on this creator","name":"fanUuid","in":"query"}],"security":[{"BearerAuth":["read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"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","null"],"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","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"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","null"],"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\n`newSubscribersCount` counts subscription **starts**, not distinct people: a returning fan who starts a new subscription is counted again. It also includes free trials, starts later refunded or charged back, fans who were later banned or deleted, and it spans profile subscriptions, checkout-link subscriptions and fan-experience subscriptions. Because of this it is normally higher than the \"New\" figure on the creator's in-app Insights dashboard, which counts first-ever profile subscribers only. Use this endpoint as the canonical daily acquisition figure.\n\n`startDate`/`endDate` offsets are honoured when selecting the window, but events are always bucketed into **UTC calendar days** — `date` is always UTC midnight. There is no timezone parameter on this endpoint, so a creator working in a non-UTC timezone should expect their local-day totals to differ from these buckets.\n\n<Info>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.subscription.activated`, `creator.subscription.deactivated` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/subscriptions).\n</Info>","operationId":"getSubscribers","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). Inclusive. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days."},"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). Inclusive. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days.","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. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days."},"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. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days.","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,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused."},"required":false,"description":"Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.","name":"size","in":"query"}],"security":[{"BearerAuth":["read:insights"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n</Info>"},"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":"Start of the UTC calendar day the events are bucketed on, as an ISO 8601 datetime string. Always UTC midnight (e.g., '2024-01-05T00:00:00.000Z'), regardless of any offset sent on startDate/endDate."},"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 subscription starts in this bucket. Counts every start, so a returning fan starting a new subscription counts again. Includes free trials and starts that were later refunded, and covers profile subscriptions, checkout-link subscriptions and fan-experience subscriptions."},"cancelledSubscribersCount":{"type":"number","description":"Number of subscription chains ending (final non-renewing expiry) in this bucket. This is a lapse, not the moment auto-renew was switched off."}},"required":["date","total","newSubscribersCount","cancelledSubscribersCount"]}},"nextCursor":{"type":["string","null"],"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.","operationId":"getTopSpenders","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:insights","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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<Note>Maximum 20 fan UUIDs per request.</Note>","operationId":"getBulkFanInsights","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"}],"security":[{"BearerAuth":["read:insights","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"responses":{"200":{"description":"Insight data about the user's fans","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["subscriber","expired","follower","not_contactable"],"description":"Current fan status"},"spending":{"type":"object","properties":{"lastPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Date of the fan's last self-initiated purchase (ISO 8601), or null if there is none. Automatic renewals never move it, and a purchase later refunded or charged back still counts, so this is recency of intent. App Store purchases do not count as a purchase here."},"lastValidPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Same as `lastPurchaseAt` but skipping purchases later refunded or charged back, so this is recency of valid spend. Null when every self-initiated purchase was reversed."},"total":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount this fan paid across all transactions, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount this fan paid across all transactions, in USD cents. Excludes App Store purchases, which record a creator buying an app from its developer rather than a fan paying this creator."}},"required":["gross","total"]},"maxSinglePayment":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Largest single payment this fan made, in USD cents. Excludes App Store purchases."}},"required":["gross","total"]},"sources":{"type":"object","additionalProperties":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount paid by the fan for this source type, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount paid by the fan for this source type, in USD cents"},"count":{"type":"integer","description":"Number of purchases the fan made from this source, counting purchases later refunded or charged back. The denominator of `average`."},"netCount":{"type":"integer","description":"Number of purchases the fan made from this source that were not later refunded or charged back. The denominator of `netAverage`."},"average":{"type":"number","description":"Average purchase from this source, in USD cents: `total` divided by `count`, so refunded and charged-back purchases count on both sides. Not rounded."},"netAverage":{"type":["number","null"],"description":"Average surviving purchase from this source, in USD cents: the sum of this source's purchases that were never refunded or charged back, divided by `netCount`. Reversed purchases are dropped from both sides. `null` when `netCount` is 0. Not rounded."}},"required":["gross","total","count","netCount","average","netAverage"]},"description":"Breakdown of spending by source. `appStore` is never present: an App Store invoice records a creator buying an app from its developer, not a fan paying this creator. `fanExperience` is fan-to-creator spend and is included."}},"required":["lastPurchaseAt","lastValidPurchaseAt","total","maxSinglePayment","sources"]},"subscription":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date-time","description":"Date subscription was created (ISO 8601) or null if no subscription"},"renewsAt":{"type":["string","null"],"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","lastValidPurchaseAt":"2024-01-14T00:00:00.000Z","total":{"gross":27700,"total":27700},"maxSinglePayment":{"gross":5000,"total":5000},"sources":{"message":{"gross":15000,"total":15000,"count":6,"netCount":5,"average":2500,"netAverage":2600},"post":{"gross":8500,"total":8500,"count":5,"netCount":5,"average":1700,"netAverage":1700},"referral":{"gross":4200,"total":4200,"count":2,"netCount":2,"average":2100,"netAverage":2100}}},"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/batch":{"post":{"summary":"Get fan insights in bulk (POST batch)","description":"Returns detailed insights for up to 100 fans in a single request, keyed by the input fan UUID.\n\nThis is the high-cap, JSON-body counterpart to `GET /insights/fans` (capped at 20 via query string). It is intended for initial-sync flows that need to hydrate many fans without per-fan round trips.\n\nPer-key errors are reported inside the 200 response body so a single forbidden or missing fan never collapses the whole request — consumers can keep partial results and only retry the failing keys.\n\n<Note>Maximum 100 fan UUIDs per request. Failed keys are reported as `{ \"error\": \"forbidden\" | \"not_found\" | \"internal\" }`.</Note>","operationId":"batchFanInsights","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:insights","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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 fan UUIDs to fetch insights for (1-100)"}},"required":["userUuids"]}}}},"responses":{"200":{"description":"Per-key insights or error for each requested fan. Always 200 when the request itself is valid, even if every key fails.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["subscriber","expired","follower","not_contactable"],"description":"Current fan status"},"spending":{"type":"object","properties":{"lastPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Date of the fan's last self-initiated purchase (ISO 8601), or null if there is none. Automatic renewals never move it, and a purchase later refunded or charged back still counts, so this is recency of intent. App Store purchases do not count as a purchase here."},"lastValidPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Same as `lastPurchaseAt` but skipping purchases later refunded or charged back, so this is recency of valid spend. Null when every self-initiated purchase was reversed."},"total":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount this fan paid across all transactions, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount this fan paid across all transactions, in USD cents. Excludes App Store purchases, which record a creator buying an app from its developer rather than a fan paying this creator."}},"required":["gross","total"]},"maxSinglePayment":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Largest single payment this fan made, in USD cents. Excludes App Store purchases."}},"required":["gross","total"]},"sources":{"type":"object","additionalProperties":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount paid by the fan for this source type, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount paid by the fan for this source type, in USD cents"},"count":{"type":"integer","description":"Number of purchases the fan made from this source, counting purchases later refunded or charged back. The denominator of `average`."},"netCount":{"type":"integer","description":"Number of purchases the fan made from this source that were not later refunded or charged back. The denominator of `netAverage`."},"average":{"type":"number","description":"Average purchase from this source, in USD cents: `total` divided by `count`, so refunded and charged-back purchases count on both sides. Not rounded."},"netAverage":{"type":["number","null"],"description":"Average surviving purchase from this source, in USD cents: the sum of this source's purchases that were never refunded or charged back, divided by `netCount`. Reversed purchases are dropped from both sides. `null` when `netCount` is 0. Not rounded."}},"required":["gross","total","count","netCount","average","netAverage"]},"description":"Breakdown of spending by source. `appStore` is never present: an App Store invoice records a creator buying an app from its developer, not a fan paying this creator. `fanExperience` is fan-to-creator spend and is included."}},"required":["lastPurchaseAt","lastValidPurchaseAt","total","maxSinglePayment","sources"]},"subscription":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date-time","description":"Date subscription was created (ISO 8601) or null if no subscription"},"renewsAt":{"type":["string","null"],"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"]},{"type":"object","properties":{"error":{"type":"string","enum":["forbidden","not_found","internal"]}},"required":["error"]}]},"description":"Map of input fan UUID to insights or a per-key error (forbidden, not_found, or internal)."},"example":{"11111111-1111-4111-8111-111111111111":{"status":"subscriber","spending":{"lastPurchaseAt":"2026-04-12T08:32:00.000Z","lastValidPurchaseAt":"2026-03-30T19:05:00.000Z","total":{"gross":12000,"total":12000},"maxSinglePayment":{"gross":5000,"total":5000},"sources":{"subscription":{"gross":7000,"total":7000,"count":7,"netCount":7,"average":1000,"netAverage":1000},"tips":{"gross":5000,"total":5000,"count":2,"netCount":0,"average":2500,"netAverage":null}}},"subscription":{"createdAt":"2026-01-15T00:00:00.000Z","renewsAt":"2026-06-15T00:00:00.000Z","autoRenewalEnabled":true}},"22222222-2222-4222-8222-222222222222":{"error":"not_found"},"33333333-3333-4333-9333-333333333333":{"error":"internal"}}}}},"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/fans/profiles":{"post":{"summary":"Get fan profiles in bulk","description":"Returns profile data (handle, display name, avatar, nickname) for up to 100 fans in a single request, keyed by the input fan UUID.\n\nThis is intended for screens that render many fans at once (avatar + display name) without per-fan round trips — the profile counterpart to `POST /insights/fans/batch`.\n\nA profile is returned only for fans connected to the creator (by subscription or follow) — the same fans `POST /insights/fans/batch` returns insights for. Per-key errors are reported inside the 200 response body so a single missing fan never collapses the whole request.\n\n<Note>Maximum 100 fan UUIDs per request. Failed keys are reported as `{ \"error\": \"not_found\" | \"internal\" }`.</Note>","operationId":"batchFanProfiles","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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 fan UUIDs to fetch profiles for (1-100)"}},"required":["userUuids"]}}}},"responses":{"200":{"description":"Per-key profile or error for each requested fan. Always 200 when the request itself is valid, even if every key fails.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt"]},{"type":"object","properties":{"error":{"type":"string","enum":["forbidden","not_found","internal"]}},"required":["error"]}]},"description":"Map of input fan UUID to the fan's profile or a per-key error (forbidden, not_found, or internal). Profiles are returned for the same fans /insights/fans/batch returns insights for — fans connected to the creator by subscription or follow."},"example":{"11111111-1111-4111-8111-111111111111":{"uuid":"11111111-1111-4111-8111-111111111111","handle":"topfan","displayName":"Top Fan","nickname":"VIP","isTopSpender":true,"avatarUrl":"https://media.fanvue.com/avatars/topfan.jpg","registeredAt":"2026-01-15T00:00:00.000Z"},"22222222-2222-4222-8222-222222222222":{"error":"not_found"},"33333333-3333-4333-9333-333333333333":{"error":"internal"}}}}},"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/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.","operationId":"getFanInsights","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Fan's UUID"},"required":true,"description":"Fan's UUID","name":"userUuid","in":"path"}],"security":[{"BearerAuth":["read:insights","read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scopes**\n\n  - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"],"format":"date-time","description":"Date of the fan's last self-initiated purchase (ISO 8601), or null if there is none. Automatic renewals never move it, and a purchase later refunded or charged back still counts, so this is recency of intent. App Store purchases do not count as a purchase here."},"lastValidPurchaseAt":{"type":["string","null"],"format":"date-time","description":"Same as `lastPurchaseAt` but skipping purchases later refunded or charged back, so this is recency of valid spend. Null when every self-initiated purchase was reversed."},"total":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount this fan paid across all transactions, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount this fan paid across all transactions, in USD cents. Excludes App Store purchases, which record a creator buying an app from its developer rather than a fan paying this creator."}},"required":["gross","total"]},"maxSinglePayment":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Largest single payment this fan made, in USD cents. Excludes App Store purchases."}},"required":["gross","total"]},"sources":{"type":"object","additionalProperties":{"type":"object","properties":{"gross":{"type":"number","description":"DEPRECATED: use `total`. Total amount paid by the fan for this source type, in USD cents. Same value as `total`."},"total":{"type":"number","description":"Total amount paid by the fan for this source type, in USD cents"},"count":{"type":"integer","description":"Number of purchases the fan made from this source, counting purchases later refunded or charged back. The denominator of `average`."},"netCount":{"type":"integer","description":"Number of purchases the fan made from this source that were not later refunded or charged back. The denominator of `netAverage`."},"average":{"type":"number","description":"Average purchase from this source, in USD cents: `total` divided by `count`, so refunded and charged-back purchases count on both sides. Not rounded."},"netAverage":{"type":["number","null"],"description":"Average surviving purchase from this source, in USD cents: the sum of this source's purchases that were never refunded or charged back, divided by `netCount`. Reversed purchases are dropped from both sides. `null` when `netCount` is 0. Not rounded."}},"required":["gross","total","count","netCount","average","netAverage"]},"description":"Breakdown of spending by source. `appStore` is never present: an App Store invoice records a creator buying an app from its developer, not a fan paying this creator. `fanExperience` is fan-to-creator spend and is included."}},"required":["lastPurchaseAt","lastValidPurchaseAt","total","maxSinglePayment","sources"]},"subscription":{"type":"object","properties":{"createdAt":{"type":["string","null"],"format":"date-time","description":"Date subscription was created (ISO 8601) or null if no subscription"},"renewsAt":{"type":["string","null"],"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","lastValidPurchaseAt":"2024-01-14T00:00:00.000Z","total":{"gross":27700,"total":27700},"maxSinglePayment":{"gross":5000,"total":5000},"sources":{"message":{"gross":15000,"total":15000,"count":6,"netCount":5,"average":2500,"netAverage":2600},"post":{"gross":8500,"total":8500,"count":5,"netCount":5,"average":1700,"netAverage":1700},"referral":{"gross":4200,"total":4200,"count":2,"netCount":2,"average":2100,"netAverage":2100}}},"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.","operationId":"createUploadSession","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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"]},"sizeBytes":{"type":"integer","exclusiveMinimum":0,"maximum":1610612736,"description":"Total size of the file in bytes. When provided, the response includes the exact `totalParts` to upload."}},"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"},"partSize":{"type":"integer","description":"Size in bytes of every part except the final one (which may be smaller)."},"maxParts":{"type":"integer","description":"Maximum number of parts allowed, derived from the maximum supported file size."},"totalParts":{"type":["integer","null"],"description":"Exact number of parts to upload, computed from `sizeBytes`. Null when `sizeBytes` was not provided — compute it client-side as ceil(fileSize / partSize)."}},"required":["mediaUuid","uploadId","partSize","maxParts","totalParts"]},"example":{"mediaUuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","uploadId":"abc123XYZ789multipart","partSize":6291456,"maxParts":854,"totalParts":4}}}},"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/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.","operationId":"getUploadPartUrl","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string"},"required":true,"name":"uploadId","in":"path"},{"schema":{"type":["number","null"]},"required":false,"name":"partNumber","in":"path"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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.","operationId":"completeUploadSession","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string"},"required":true,"name":"uploadId","in":"path"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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    Each finalised media item includes a `tags` field containing structured AI\n    content tags (description, tags, NSFW classification, scene/setting, etc.)\n    when the owning creator has AI content tagging enabled and the media has\n    been processed. `tags` is `null` otherwise.","operationId":"getUserMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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","description":"Case-insensitive substring match on the media name."},"required":false,"description":"Case-insensitive substring match on the media name.","name":"name","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter to media created on or after this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-20T00:00:00Z)."},"required":false,"description":"Filter to media created on or after this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter to media created before this ISO 8601 datetime (non-inclusive, with optional timezone offset)."},"required":false,"description":"Filter to media created before this ISO 8601 datetime (non-inclusive, with optional timezone offset).","name":"endDate","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}],"security":[{"BearerAuth":["read:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"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"},"total":{"type":"integer","description":"Total number of media items matching the query across all pages"}},"required":["page","size","hasMore","total"],"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,"tags":{"description":"Behind-the-scenes shot at sunset on a beach.","tags":["beach","sunset","outdoors"],"nsfwCategory":[],"sexActs":[],"bodyParts":[],"people":["solo woman"],"sexObjects":[],"setting":["beach","sunset"],"position":[],"skinColor":[],"bodyType":[],"hairColor":["blonde"],"otherTags":[],"importantTags":["beach"],"isNsfw":false,"mediaType":"video"},"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,"total":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"}}}},"/media/bulk":{"get":{"summary":"Get bulk media by UUIDs","description":"Returns multiple media items in a single request.\n\nEach finalised media item includes a `tags` field containing structured AI\ncontent tags when the owning creator has AI content tagging enabled and the\nmedia has been processed (`null` otherwise).\n\n<Note>Maximum 20 media UUIDs per request.</Note>","operationId":"getBulkMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string"},"required":true,"name":"mediaUuids","in":"query"},{"schema":{"type":"string"},"required":false,"name":"variants","in":"query"}],"security":[{"BearerAuth":["read:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"required":["uuid","status","createdAt","caption","description","name","mediaType","recommendedPrice"]},{"type":"null"}]},"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,"tags":{"description":"Behind-the-scenes shot at sunset on a beach.","tags":["beach","sunset","outdoors"],"nsfwCategory":[],"sexActs":[],"bodyParts":[],"people":["solo woman"],"sexObjects":[],"setting":["beach","sunset"],"position":[],"skinColor":[],"bodyType":[],"hairColor":["blonde"],"otherTags":[],"importantTags":["beach"],"isNsfw":false,"mediaType":"image"},"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"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"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, plus a\n    `tags` field containing structured AI content tags when the owning\n    creator has AI content tagging enabled and the media has been processed\n    (`null` otherwise).\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>","operationId":"getUserMediaByUuid","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}],"security":[{"BearerAuth":["read:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"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,"tags":{"description":"Behind-the-scenes shot at sunset on a beach.","tags":["beach","sunset","outdoors"],"nsfwCategory":[],"sexActs":[],"bodyParts":[],"people":["solo woman"],"sexObjects":[],"setting":["beach","sunset"],"position":[],"skinColor":[],"bodyType":[],"hairColor":["blonde"],"otherTags":[],"importantTags":["beach"],"isNsfw":false,"mediaType":"image"},"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"}}},"delete":{"summary":"Delete media from vault","description":"Soft-deletes a media item from the authenticated user's vault.\n\n    The media is detached from any vault folders and removed from vault listings.\n    Copies already distributed elsewhere (sent in messages, attached to posts, or\n    previously purchased) are not affected and remain accessible to their recipients.","operationId":"deleteMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"responses":{"204":{"description":"Media deleted from vault"},"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 media name, caption and recommended price","description":"Update the name, caption and/or recommended price of a media item owned by the\n    authenticated user.\n\n    Only `name`, `caption` and `recommendedPrice` can be changed. Omit a field to leave it\n    unchanged, or pass `null` to clear it. At least one field must be provided.","operationId":"updateMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Display name. Pass null to clear it; omit to leave unchanged."},"caption":{"type":["string","null"],"maxLength":5000,"description":"Caption. Pass null to clear it; omit to leave unchanged."},"recommendedPrice":{"type":["integer","null"],"minimum":0,"maximum":50000,"description":"Recommended price in cents. Pass null to clear it; omit to leave unchanged."}}}}}},"responses":{"200":{"description":"Updated media item","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"caption":{"type":["string","null"]},"recommendedPrice":{"type":["number","null"]}},"required":["uuid","name","caption","recommendedPrice"]},"example":{"uuid":"d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a","name":"Beach photoshoot","caption":"Golden hour by the sea 🌅","recommendedPrice":1500}}}},"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.","operationId":"grantMedia","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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    Finalised responses include a `tags` field with structured AI content\n    tags when the owning creator has AI content tagging enabled and the media\n    has been processed (`null` otherwise).\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>","operationId":"getEntitledMedia","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}],"security":[{"BearerAuth":["read:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"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,"tags":{"description":"Behind-the-scenes shot at sunset on a beach.","tags":["beach","sunset","outdoors"],"nsfwCategory":[],"sexActs":[],"bodyParts":[],"people":["solo woman"],"sexObjects":[],"setting":["beach","sunset"],"position":[],"skinColor":[],"bodyType":[],"hairColor":["blonde"],"otherTags":[],"importantTags":["beach"],"isNsfw":false,"mediaType":"image"},"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.","operationId":"getMediaLinkPurchaseStatus","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path"}],"security":[{"BearerAuth":["read:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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"}}}},"/media-links":{"get":{"summary":"List media links","description":"List the authenticated creator's media links, newest first. Soft-deleted links, and links whose media is no longer available, are excluded. All amounts are integer minor units of the currency (e.g. cents).","operationId":"listMediaLinks","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of media links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Media link UUID"},"url":{"type":["string","null"],"description":"Shareable URL fans use to unlock the media"},"price":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents) fans pay to unlock"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"UUIDs of the media items bundled into the link, oldest first"},"clicks":{"type":"integer","description":"Number of times the link has been viewed"},"unlocks":{"type":"integer","description":"Number of paid unlocks (completed purchases)"},"earnings":{"type":"integer","description":"Total gross earnings from the link, in integer minor units of the currency"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","url","price","mediaUuids","clicks","unlocks","earnings","createdAt"]},"description":"The creator's media links, newest first"},"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":"b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e","url":"https://www.fanvue.com/creatorhandle/media/fvml-12","price":1999,"mediaUuids":["c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f","d5e6f7a8-9b0c-4d1e-af2a-3b4c5d6e7f8a"],"clicks":128,"unlocks":14,"earnings":27986,"createdAt":"2024-01-15T00:00:00.000Z"},{"uuid":"e6f7a8b9-0c1d-4e2f-ba3b-4c5d6e7f8a9b","url":"https://www.fanvue.com/creatorhandle/media/fvml-11","price":500,"mediaUuids":["f7a8b9c0-1d2e-4f3a-8b4c-5d6e7f8a9b0c"],"clicks":42,"unlocks":0,"earnings":0,"createdAt":"2024-01-14T00:00:00.000Z"}],"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"}}},"post":{"summary":"Create a media link","description":"Create a shareable media link that bundles one or more vault media items for a single unlock price. All referenced media must be owned by the creator. Amounts are integer minor units of the currency (e.g. cents: 1999 = $19.99). Requires media links to be enabled.","operationId":"createMediaLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"description":"UUIDs of the vault media items to bundle into the link. All must be owned by the creator."},"price":{"type":"integer","minimum":300,"maximum":50000,"description":"Price fans pay to unlock the media, in integer minor units of the currency (e.g. cents: 1999 = $19.99). Must be between 300 and 50000 minor units. Note: the Fanvue dashboard displays prices in major units; this API always uses integer minor units."}},"required":["mediaUuids","price"]}}}},"responses":{"201":{"description":"Media link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Media link UUID"},"url":{"type":["string","null"],"description":"Shareable URL fans use to unlock the media"},"price":{"type":"integer","description":"Price in integer minor units of the currency (e.g. cents) fans pay to unlock"},"mediaUuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"UUIDs of the media items bundled into the link, oldest first"},"clicks":{"type":"integer","description":"Number of times the link has been viewed"},"unlocks":{"type":"integer","description":"Number of paid unlocks (completed purchases)"},"earnings":{"type":"integer","description":"Total gross earnings from the link, in integer minor units of the currency"},"createdAt":{"type":"string","format":"date-time","description":"When the link was created"}},"required":["uuid","url","price","mediaUuids","clicks","unlocks","earnings","createdAt"]},"example":{"uuid":"b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e","url":"https://www.fanvue.com/creatorhandle/media/fvml-12","price":1999,"mediaUuids":["c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f","d5e6f7a8-9b0c-4d1e-af2a-3b4c5d6e7f8a"],"clicks":128,"unlocks":14,"earnings":27986,"createdAt":"2024-01-15T00:00:00.000Z"}}}},"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}":{"delete":{"summary":"Delete a media link","description":"Soft-delete a media link so it can no longer be viewed or purchased. Deletion is terminal. Past purchases keep their access.","operationId":"deleteMediaLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Media link UUID"},"required":true,"description":"Media link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Media 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"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"410":{"$ref":"#/components/responses/SunsetVersionResponse"},"429":{"$ref":"#/components/responses/RateLimitResponse"}}}},"/notifications":{"get":{"summary":"Get notifications feed","description":"Returns a paginated list of notifications for the authenticated user, ordered by most recent first. Optionally filter by event type.\n\n<Info>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to webhooks instead — most engagement and payment activity in this feed (messages, follows, likes, comments, subscriptions, and payments) is delivered in real time by the individual webhook events. See the full event catalogue in the [webhook documentation](https://api.fanvue.com/docs/creator/overview). Some system notifications (promotions, account health, poll results, and fan churn risk) have no webhook equivalent yet and remain available only from this endpoint.\n</Info>","operationId":"listNotifications","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"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":"integer","description":"Filter notifications by event type id"},"required":false,"description":"Filter notifications by event type id","name":"eventType","in":"query"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"200":{"description":"List of notifications","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"eventType":{"type":"integer","description":"Numeric event id (6=post comment, 7=post like, 9=purchase, 10=new subscriber, 11=tip, 12=new follower, 14=promotion, 19=creator promo payment, 26=account health, 27=poll closed, 28=fan churn risk)"},"isRead":{"type":"boolean"},"data":{"type":"object","additionalProperties":{},"description":"Event-specific payload. Shape varies by eventType."},"originator":{"type":["object","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"avatarUrl":{"type":["string","null"]},"isCreator":{"type":"boolean"}},"required":["uuid","handle","displayName","avatarUrl","isCreator"]},"receiverUuid":{"type":"string","format":"uuid","description":"UUID of the user who received the notification"}},"required":["uuid","createdAt","eventType","isRead","data","originator","receiverUuid"]},"description":"Array of notifications"},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page, or null if none"}},"required":["data","nextCursor"]},"example":{"data":[{"uuid":"6c3d8b1c-9b1f-4b6e-8d77-4e8b22ff9a01","createdAt":"2026-05-22T08:30:00.000Z","eventType":11,"isRead":false,"data":{"price":500},"originator":{"uuid":"8a3a93e2-1c2a-4b6c-b4fd-1cdaaa6fbc11","handle":"sarahmiller","displayName":"Sarah Miller","avatarUrl":"https://media.fanvue.com/avatars/sarahmiller.jpg","isCreator":false},"receiverUuid":"2bde24e6-942b-49d4-b7b9-8d1e8eccbffb"},{"uuid":"f1d2e3b4-aaaa-4f5b-9c1d-2c2dffe11a23","createdAt":"2026-05-21T18:12:43.000Z","eventType":12,"isRead":true,"data":{},"originator":{"uuid":"21f5c1ab-7d22-4e7d-9c2b-e1c3a4f6bb22","handle":"mikejohnson","displayName":"Mike Johnson","avatarUrl":null,"isCreator":false},"receiverUuid":"2bde24e6-942b-49d4-b7b9-8d1e8eccbffb"}],"nextCursor":"eyJvZmZzZXQiOjIwfQ"}}}},"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"}}}},"/onboarding/creators":{"post":{"summary":"Onboard a creator","description":"Create a pre-filled Fanvue creator signup from the supplied details.\n\nThe account is provisioned with the given banking country, content category and subscription price already completed, and a pending identity-verification (KYC) session is started for it. The response includes `kycUrl`, the hosted verification link: give it to the creator so they can complete verification. Verification is performed entirely by Fanvue's verification provider — this API only initiates the session and never sees or influences the verification itself. A verification email is sent to the creator's address as part of signup.\n\nThe account is not yet an active creator: it becomes active once the creator passes verification and completes profile setup in the standard Fanvue onboarding flow (which is also where they land on first login if the link is lost).\n\n<Info>Access is limited to approved partner applications. Contact Fanvue to have your application enabled for creator onboarding. Requests are additionally capped per application per day.</Info>","operationId":"onboardCreator","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address for the new creator account"},"password":{"type":"string","pattern":"^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).{9,30}$","description":"Password for the new account (9-30 characters, at least one uppercase letter, one lowercase letter and one number). When omitted, an unguessable random password is generated; the creator can gain access via the standard password-reset flow."},"handle":{"type":"string","description":"Fanvue handle for the new creator. When omitted, a unique handle is generated."},"displayName":{"type":"string","minLength":1,"maxLength":50,"description":"Display name for the new creator. Defaults to a name derived from the handle."},"bankingCountry":{"type":"string","pattern":"^[A-Z]{2}$","description":"Payout country of the creator (ISO 3166-1 alpha-2, e.g. GB)"},"contentType":{"type":"string","enum":["GENERAL","NSFW"],"default":"GENERAL","description":"Content category for the new creator"},"isAiCreator":{"type":"boolean","default":false,"description":"Whether this is an AI creator"},"subscriptionPrice":{"type":"integer","minimum":399,"maximum":10000,"description":"Monthly subscription price in USD cents (399-10000)"}},"required":["email","bankingCountry","subscriptionPrice"]}}}},"responses":{"201":{"description":"Creator signup created with a pending verification session","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","description":"UUID of the newly created creator"},"handle":{"type":"string","description":"Handle of the newly created creator"},"displayName":{"type":"string","description":"Display name of the newly created creator"},"email":{"type":"string","description":"Email address of the newly created creator"},"kycUrl":{"type":["string","null"],"description":"Hosted identity-verification URL. Give this link to the creator so they can complete KYC; verification is performed entirely by Fanvue's verification provider. Null when a verification session could not be started — the creator can still verify by logging in to Fanvue."}},"required":["uuid","handle","displayName","email","kycUrl"]},"example":{"uuid":"b7e6a2a0-1c2d-4e3f-9a4b-5c6d7e8f9a0b","handle":"amazing-falcon-123","displayName":"Amazing Falcon","email":"creator@example.com","kycUrl":"https://idv.ondato.com/?id=1eb2f0cc-4ba4-4b71-9e42-4b4b0d6c1a2f"}}}},"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"}}}},"/posts":{"post":{"summary":"Create a new post","description":"Create a new post with optional media, text, and pricing.","operationId":"createPost","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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).","operationId":"getPosts","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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"},{"schema":{"type":"string","format":"date-time","description":"Only include posts created on or after this ISO 8601 datetime (e.g., 2024-10-20T00:00:00Z)."},"required":false,"description":"Only include posts created on or after this ISO 8601 datetime (e.g., 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include posts created before this ISO 8601 datetime (non-inclusive)."},"required":false,"description":"Only include posts created before this ISO 8601 datetime (non-inclusive).","name":"endDate","in":"query"}],"security":[{"BearerAuth":["read:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"getPostByUuid","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"}],"security":[{"BearerAuth":["read:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"updatePost","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"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":["string","null"],"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","null"],"format":"uuid","description":"UUID of free preview media shown before unlock. Set to null to remove."},"price":{"type":["number","null"],"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","null"],"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","null"],"format":"date-time","description":"Date/time when the post expires (ISO 8601 format). Set to null to remove expiration."},"collectionUuids":{"type":["array","null"],"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"deletePost","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"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"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>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `tip.new` webhook event instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/payments).\n</Info>","operationId":"getPostTips","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n</Info>"},"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","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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","null"],"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>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.post.liked` webhook event instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/engagement).\n</Info>","operationId":"getPostLikes","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n</Info>"},"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","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"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>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.post.commented` webhook event instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/engagement).\n</Info>","operationId":"getPostComments","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":"integer","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":"integer","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"}],"security":[{"BearerAuth":["read:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:post` — Read posts, including post details, comments, likes, and tips.\n</Info>"},"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","null"],"properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"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","null"],"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.","operationId":"createPostComment","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"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"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","null"],"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.","operationId":"repostPost","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"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"pinPost","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"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"unpinPost","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"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"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","null"],"description":"Text content of the post"},"price":{"type":["number","null"],"description":"Price in cents for paid posts"},"mediaPreviewUuid":{"type":["string","null"],"format":"uuid","description":"UUID of free preview media"},"audience":{"$ref":"#/components/schemas/PostAudience"},"publishAt":{"type":["string","null"],"format":"date-time","description":"Future date/time when the post will be published (ISO 8601 format)"},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Date/time when the post was published (ISO 8601 format)"},"expiresAt":{"type":["string","null"],"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.","operationId":"deletePostComment","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"}],"security":[{"BearerAuth":["write:post"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:post` — Create, edit, and manage posts and content on behalf of users.\n</Info>"},"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"}}}},"/promotions":{"get":{"summary":"List promotions","description":"List the authenticated creator's active (non-stopped) subscription promotions.","operationId":"listPromotions","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:creator` — Access creator profiles, content, and creator-specific information.\n</Info>"},"responses":{"200":{"description":"List of promotions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Promotion UUID"},"type":{"type":"string","enum":["discount","free_trial"],"description":"Whether the promotion is a first-month discount or a free trial"},"discountPercent":{"type":["integer","null"],"description":"Discount percentage (null for free-trial promotions)"},"freeTrialDays":{"type":["integer","null"],"description":"Free trial length in days (null for discount promotions)"},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"endsAt":{"type":["string","null"],"format":"date-time","description":"When the promotion expires (null if it never expires)"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"usedCount":{"type":"integer","description":"Number of times the promotion has been redeemed"},"message":{"type":["string","null"],"description":"Message shown to fans with the promotion"},"createdAt":{"type":"string","format":"date-time","description":"When the promotion was created"}},"required":["uuid","type","discountPercent","freeTrialDays","availableToGroup","endsAt","maxUsages","usedCount","message","createdAt"]},"description":"The creator's active (non-stopped) promotions"}},"required":["data"]},"example":{"data":[{"uuid":"d4e5f6a7-8b9c-4d1e-a2b3-c4d5e6f7a8b9","type":"discount","discountPercent":20,"freeTrialDays":null,"availableToGroup":"new_subscribers","endsAt":"2024-02-15T00:00:00.000Z","maxUsages":100,"usedCount":12,"message":"20% off your first month!","createdAt":"2024-01-15T00:00:00.000Z"},{"uuid":"e5f6a7b8-9c0d-4e2f-b3c4-d5e6f7a8b9c0","type":"free_trial","discountPercent":null,"freeTrialDays":7,"availableToGroup":"followers","endsAt":null,"maxUsages":null,"usedCount":3,"message":null,"createdAt":"2024-01-14T00:00:00.000Z"}]}}}},"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 promotion","description":"Create a promotional subscription offer: either a first-month discount (`discountPercent`) or a free trial, never both. For a free trial, set `freeTrialDays` (1-30), or set `freeTrial: true` without `freeTrialDays` for an unlimited (free-forever) trial.\n\nCreating a promotion replaces any existing promotion targeting the same audience group, and eligible fans are notified.","operationId":"createPromotion","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"discountPercent":{"type":"integer","minimum":1,"maximum":100,"description":"First-month discount as a percentage of the subscription price. Mutually exclusive with a free trial."},"freeTrial":{"type":"boolean","description":"Set to true to offer a free trial. Combine with freeTrialDays for a fixed length, or omit freeTrialDays for an unlimited (free-forever) trial. Mutually exclusive with discountPercent. Passing freeTrialDays alone also implies a free trial."},"freeTrialDays":{"type":"integer","minimum":1,"maximum":30,"description":"Length of the free trial in days (1-30). Omit while freeTrial is true for an unlimited (free-forever) trial. Mutually exclusive with discountPercent."},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"maxUsages":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum number of redemptions. Unlimited when omitted."},"endsAt":{"type":"string","format":"date-time","description":"When the promotion stops being redeemable. Never expires when omitted."},"message":{"type":"string","description":"Optional message shown to fans with the promotion"}},"required":["availableToGroup"]}}}},"responses":{"201":{"description":"Promotion created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Promotion UUID"},"type":{"type":"string","enum":["discount","free_trial"],"description":"Whether the promotion is a first-month discount or a free trial"},"discountPercent":{"type":["integer","null"],"description":"Discount percentage (null for free-trial promotions)"},"freeTrialDays":{"type":["integer","null"],"description":"Free trial length in days (null for discount promotions)"},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"endsAt":{"type":["string","null"],"format":"date-time","description":"When the promotion expires (null if it never expires)"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"usedCount":{"type":"integer","description":"Number of times the promotion has been redeemed"},"message":{"type":["string","null"],"description":"Message shown to fans with the promotion"},"createdAt":{"type":"string","format":"date-time","description":"When the promotion was created"}},"required":["uuid","type","discountPercent","freeTrialDays","availableToGroup","endsAt","maxUsages","usedCount","message","createdAt"]},"example":{"uuid":"d4e5f6a7-8b9c-4d1e-a2b3-c4d5e6f7a8b9","type":"discount","discountPercent":20,"freeTrialDays":null,"availableToGroup":"new_subscribers","endsAt":"2024-02-15T00:00:00.000Z","maxUsages":100,"usedCount":12,"message":"20% off your first month!","createdAt":"2024-01-15T00:00:00.000Z"}}}},"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"}}}},"/promotions/{promotionUuid}":{"put":{"summary":"Edit a promotion","description":"Edit a promotion by replacing it, exactly like editing from the dashboard: the referenced promotion is stopped, a new promotion is created with the provided values, and eligible fans are notified of the updated offer.\n\nThe response contains the replacement promotion, whose `uuid` differs from the one in the path and whose `usedCount` starts at zero. Fans who redeemed the original promotion keep their discounted price or trial. If the new values target a different audience group, any existing promotion for that audience is also replaced.","operationId":"updatePromotion","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Promotion UUID"},"required":true,"description":"Promotion UUID","name":"promotionUuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"discountPercent":{"type":"integer","minimum":1,"maximum":100,"description":"First-month discount as a percentage of the subscription price. Mutually exclusive with a free trial."},"freeTrial":{"type":"boolean","description":"Set to true to offer a free trial. Combine with freeTrialDays for a fixed length, or omit freeTrialDays for an unlimited (free-forever) trial. Mutually exclusive with discountPercent. Passing freeTrialDays alone also implies a free trial."},"freeTrialDays":{"type":"integer","minimum":1,"maximum":30,"description":"Length of the free trial in days (1-30). Omit while freeTrial is true for an unlimited (free-forever) trial. Mutually exclusive with discountPercent."},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"maxUsages":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum number of redemptions. Unlimited when omitted."},"endsAt":{"type":"string","format":"date-time","description":"When the promotion stops being redeemable. Never expires when omitted."},"message":{"type":"string","description":"Optional message shown to fans with the promotion"}},"required":["availableToGroup"]}}}},"responses":{"200":{"description":"Promotion updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Promotion UUID"},"type":{"type":"string","enum":["discount","free_trial"],"description":"Whether the promotion is a first-month discount or a free trial"},"discountPercent":{"type":["integer","null"],"description":"Discount percentage (null for free-trial promotions)"},"freeTrialDays":{"type":["integer","null"],"description":"Free trial length in days (null for discount promotions)"},"availableToGroup":{"type":"string","enum":["new_subscribers","expired_subscribers","all","followers"],"description":"Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all"},"endsAt":{"type":["string","null"],"format":"date-time","description":"When the promotion expires (null if it never expires)"},"maxUsages":{"type":["integer","null"],"description":"Maximum number of redemptions (null if unlimited)"},"usedCount":{"type":"integer","description":"Number of times the promotion has been redeemed"},"message":{"type":["string","null"],"description":"Message shown to fans with the promotion"},"createdAt":{"type":"string","format":"date-time","description":"When the promotion was created"}},"required":["uuid","type","discountPercent","freeTrialDays","availableToGroup","endsAt","maxUsages","usedCount","message","createdAt"]},"example":{"uuid":"d4e5f6a7-8b9c-4d1e-a2b3-c4d5e6f7a8b9","type":"discount","discountPercent":20,"freeTrialDays":null,"availableToGroup":"new_subscribers","endsAt":"2024-02-15T00:00:00.000Z","maxUsages":100,"usedCount":12,"message":"20% off your first month!","createdAt":"2024-01-15T00: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"}}},"delete":{"summary":"Stop a promotion","description":"Stop a promotion so it can no longer be redeemed. Fans who already redeemed it keep their discounted price or trial.","operationId":"deletePromotion","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Promotion UUID"},"required":true,"description":"Promotion UUID","name":"promotionUuid","in":"path"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"responses":{"204":{"description":"Promotion stopped 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>\n  **Polling for real-time updates? Use a webhook instead.**\n\n  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.subscription.activated`, `creator.subscription.cancel_at_period_end_changed`, `creator.subscription.deactivated` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/subscriptions).\n</Info>","operationId":"listSubscribers","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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"},{"schema":{"type":"string","format":"date-time","description":"Only include users whose subscription started on or after this ISO 8601 datetime (e.g., 2024-10-20T00:00:00Z)."},"required":false,"description":"Only include users whose subscription started on or after this ISO 8601 datetime (e.g., 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include users whose subscription started before this ISO 8601 datetime (non-inclusive)."},"required":false,"description":"Only include users whose subscription started before this ISO 8601 datetime (non-inclusive).","name":"endDate","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor from a previous response's pagination.nextCursor. When provided, page, sortField, sortDirection, startDate, and endDate are ignored (the cursor carries them); size applies when explicitly passed. Cursor pagination is more efficient than page-based pagination for iterating over large subscriber lists."},"required":false,"description":"Opaque pagination cursor from a previous response's pagination.nextCursor. When provided, page, sortField, sortDirection, startDate, and endDate are ignored (the cursor carries them); size applies when explicitly passed. Cursor pagination is more efficient than page-based pagination for iterating over large subscriber lists.","name":"cursor","in":"query"}],"security":[{"BearerAuth":["read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"},"subscription":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["active","cancelled","pending_confirmation","paused"],"description":"Current status of the subscriber's subscription to this creator"},"price":{"type":"number","description":"Configured subscription price per period, in minor currency units (cents). This is the list price and does not reflect discounts or free trials — see `amountPaid` for the actual amount charged."},"amountPaid":{"type":"number","description":"Amount actually charged for the current period, in minor currency units (cents), after any discount. 0 when nothing has been charged yet (e.g. a fan inside a free trial)."},"currentPeriodStart":{"type":"string","format":"date-time","description":"Start of the current subscription period (ISO 8601)"},"currentPeriodEnd":{"type":["string","null"],"format":"date-time","description":"End of the current subscription period / next renewal date (ISO 8601), or null"},"autoRenewalEnabled":{"type":"boolean","description":"Whether the subscription is set to auto-renew (rebill) at the end of the period"}},"required":["status","price","amountPaid","currentPeriodStart","currentPeriodEnd","autoRenewalEnabled"],"description":"Details of the subscriber's current subscription to the creator, or null if none is found"},"firstSubscribedAt":{"type":["string","null"],"format":"date-time","description":"When the fan first subscribed to the creator (earliest across their whole subscription history), used to tell a genuinely new fan from a re-subscriber. Null if unknown."}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt","subscription","firstSubscribedAt"]},"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"},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page; pass it as the cursor query parameter. Null when there are no further results, or when sorting by name (cursor pagination is only supported for the subscribedAt sort)."}},"required":["page","size","hasMore","nextCursor"],"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","subscription":{"status":"active","price":999,"amountPaid":999,"currentPeriodStart":"2026-05-15T00:00:00.000Z","currentPeriodEnd":"2026-06-15T00:00:00.000Z","autoRenewalEnabled":true},"firstSubscribedAt":"2025-11-15T00:00:00.000Z"},{"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","subscription":{"status":"cancelled","price":1499,"amountPaid":1499,"currentPeriodStart":"2026-06-01T00:00:00.000Z","currentPeriodEnd":"2026-07-01T00:00:00.000Z","autoRenewalEnabled":false},"firstSubscribedAt":"2026-06-01T00:00:00.000Z"}],"pagination":{"page":1,"size":2,"hasMore":false,"nextCursor":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"}}}},"/subscribers/{userUuid}":{"get":{"summary":"Get subscriber by user UUID","description":"Returns a single subscriber of the authenticated user by their user UUID, including their subscription details. Returns 404 if the user is not a subscriber.","operationId":"getSubscriber","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"UUID of the subscriber to retrieve"},"required":true,"description":"UUID of the subscriber to retrieve","name":"userUuid","in":"path"}],"security":[{"BearerAuth":["read:fan"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:fan` — Access fan-related data and information within the platform.\n</Info>"},"responses":{"200":{"description":"Subscriber details","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"handle":{"type":"string"},"displayName":{"type":"string"},"nickname":{"type":["string","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":"string","format":"date-time"},"subscription":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["active","cancelled","pending_confirmation","paused"],"description":"Current status of the subscriber's subscription to this creator"},"price":{"type":"number","description":"Configured subscription price per period, in minor currency units (cents). This is the list price and does not reflect discounts or free trials — see `amountPaid` for the actual amount charged."},"amountPaid":{"type":"number","description":"Amount actually charged for the current period, in minor currency units (cents), after any discount. 0 when nothing has been charged yet (e.g. a fan inside a free trial)."},"currentPeriodStart":{"type":"string","format":"date-time","description":"Start of the current subscription period (ISO 8601)"},"currentPeriodEnd":{"type":["string","null"],"format":"date-time","description":"End of the current subscription period / next renewal date (ISO 8601), or null"},"autoRenewalEnabled":{"type":"boolean","description":"Whether the subscription is set to auto-renew (rebill) at the end of the period"}},"required":["status","price","amountPaid","currentPeriodStart","currentPeriodEnd","autoRenewalEnabled"],"description":"Details of the subscriber's current subscription to the creator, or null if none is found"},"firstSubscribedAt":{"type":["string","null"],"format":"date-time","description":"When the fan first subscribed to the creator (earliest across their whole subscription history), used to tell a genuinely new fan from a re-subscriber. Null if unknown."}},"required":["uuid","handle","displayName","nickname","isTopSpender","avatarUrl","registeredAt","subscription","firstSubscribedAt"]},"example":{"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","subscription":{"status":"active","price":999,"currentPeriodStart":"2026-05-15T00:00:00.000Z","currentPeriodEnd":"2026-06-15T00:00:00.000Z","autoRenewalEnabled":true},"firstSubscribedAt":"2025-11-15T00: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"}}}},"/tracking-links":{"get":{"summary":"List tracking links","description":"List authenticated user's tracking links with cursor-based pagination.","operationId":"listTrackingLinks","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","exclusiveMinimum":0,"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"}],"security":[{"BearerAuth":["read:tracking_links"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n</Info>"},"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, including clicks that were never matched to an account. This is why the count can exceed the number of users returned by the tracking-link users endpoint, which can only list identified clickers."},"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","null"],"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","null"],"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\nThe response `linkUrl` is the short slug (for example `fv-3`); the shareable URL is `https://www.fanvue.com/<handle>/<linkUrl>`. To attribute a click to a campaign or a record in your own system, append your own query parameters to that URL and read them back from the user-metadata endpoint. See the [tracking links guide](https://api.fanvue.com/docs/tutorials/tracking-links).","operationId":"createTrackingLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:tracking_links"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:tracking_links` — Create and delete tracking links.\n</Info>"},"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, including clicks that were never matched to an account. This is why the count can exceed the number of users returned by the tracking-link users endpoint, which can only list identified clickers."},"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","null"],"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.","operationId":"deleteTrackingLink","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Tracking link UUID"},"required":true,"description":"Tracking link UUID","name":"uuid","in":"path"}],"security":[{"BearerAuth":["write:tracking_links"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:tracking_links` — Create and delete tracking links.\n</Info>"},"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"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"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\nOnly clicks that could be matched to an account appear here, so this list is a subset of the link's `clicks` count. A user who clicked without ever signing in cannot be identified and is omitted.\n\nUsers who clicked but never subscribed or followed are included, with `status` and the conversion dates set to null.","operationId":"listTrackingLinkUsers","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","exclusiveMinimum":0,"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"}],"security":[{"BearerAuth":["read:tracking_links"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n</Info>"},"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","null"]},"isTopSpender":{"type":"boolean"},"avatarUrl":{"type":["string","null"]},"registeredAt":{"type":["string","null"],"format":"date-time","description":"When the user converted (subscribed to or followed the creator) via this tracking link — the conversion attributed to the link. Despite the name this is not the account-creation date. Reflects the relationship matching the user's current status, and is null when there is no current relationship or when the conversion pre-dates the user's first click on this link (so it was not driven by it). For subscribers the conversion is the start of the subscription currently on file, so a fan who lapsed and resubscribed through this link is attributed to it. For the raw relationship dates regardless of attribution, see subscribedAt / followedAt."},"subscribedAt":{"type":["string","null"],"format":"date-time","description":"When the user first subscribed to the creator, regardless of whether the subscription is attributed to this link. Does not advance when a lapsed fan resubscribes — see currentSubscriptionStartedAt for the start of the subscription currently on file. Null if the user has no subscription to the creator."},"currentSubscriptionStartedAt":{"type":["string","null"],"format":"date-time","description":"When the subscription currently on file began: the most recent resubscribe, or the same value as subscribedAt when the fan never lapsed. Unaffected by renewals. Null if the user has no subscription to the creator."},"followedAt":{"type":["string","null"],"format":"date-time","description":"When the user followed the creator, regardless of whether the follow is attributed to this link. Null if the user does not follow the creator."},"clickedAt":{"type":["string","null"],"format":"date-time","description":"When the user first clicked this tracking link."},"status":{"type":["string","null"],"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","subscribedAt","currentSubscriptionStartedAt","followedAt","clickedAt","status"]},"description":"Users associated with this tracking link"},"nextCursor":{"type":["string","null"],"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","subscribedAt":"2023-11-02T00:00:00.000Z","currentSubscriptionStartedAt":"2024-01-15T00:00:00.000Z","followedAt":null,"clickedAt":"2024-01-14T00: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","subscribedAt":null,"currentSubscriptionStartedAt":null,"followedAt":"2024-01-14T00:00:00.000Z","clickedAt":"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\nMetadata is captured from the query string of the shared short link (`https://www.fanvue.com/<handle>/fv-3?campaign=spring_launch`), using plain query parameters rather than the `metadata[<key>]` syntax checkout links use. Every non-reserved parameter is captured as-is, trimmed to 10 keys and 500 characters per value; over-limit input is silently trimmed rather than rejected.\n\nOnly the most recent impression is returned, and metadata is never merged across clicks: a later click replaces the previous values wholesale, and a later click with no query parameters returns `null`.\n\nReturns 404 when the link is not one of the creator's, and 200 with `metadata: null` when the user has no attributed impression carrying usable metadata.\n\nSee the [tracking links guide](https://api.fanvue.com/docs/tutorials/tracking-links) for the full mechanism, limits and worked examples.","operationId":"getUserTrackingMetadata","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"}],"security":[{"BearerAuth":["read:tracking_links"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n</Info>"},"responses":{"200":{"description":"User's tracking metadata","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom metadata from the user's most recent impression on this link, captured from the query string of the shared short link. Null when the user has no attributed impression carrying usable metadata, including when their latest click carried no query parameters."}},"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.","operationId":"getCurrentUser","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"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"},"roles":{"type":"array","items":{"type":"string","enum":["creator","agency","agency_admin"]},"description":"Full non-exclusive set of roles held by the account. Unlike `isCreator`, this expresses that an account can be several things at once (e.g. a creator who also manages an agency). `isCreator` is retained and always equals `roles.includes(\"creator\")`."},"isDiscoverable":{"type":"boolean","description":"Whether the profile is eligible to appear in Discovery. Reflects the creator's discoverability setting; it is turned off when the account is restricted or fails moderation. Final placement in Discovery and Suggestions feeds also depends on ranking and per-viewer filters, so being discoverable does not guarantee appearance for every viewer. Always false for non-creators."},"isInCuratedSection":{"type":"boolean","description":"Whether the creator is currently surfaced in Discovery/Suggestions via the manager-controlled recommendation flag. Unlike `isDiscoverable` (which is only eligibility), this reflects active curation and is the signal that a model is being surfaced. Final placement for any given viewer still depends on ranking and per-viewer filters (e.g. already-following, country), so this does not guarantee appearance for every viewer. Always false for non-creators."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"avatarUrl":{"type":["string","null"]},"bannerUrl":{"type":["string","null"]},"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","roles","isDiscoverable","isInCuratedSection","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,"roles":["creator"],"isDiscoverable":true,"isInCuratedSection":false,"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"}}}},"/users/account":{"get":{"summary":"Get current user's account","description":"Get the authenticated user's account view: profile, status, earnings totals, last payout, and fan counts.","operationId":"getAccount","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"200":{"description":"Current user's account details","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"handle":{"type":"string"},"displayName":{"type":"string"},"isCreator":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"avatarUrl":{"type":["string","null"]},"bannerUrl":{"type":["string","null"]},"bio":{"type":"string"},"account":{"type":"object","properties":{"status":{"type":"string","enum":["active","suspended"],"description":"Account lifecycle status"},"subscriptionPrice":{"type":["integer","null"],"description":"Current monthly subscription price in USD cents (minor units), or null when no price is set (e.g. non-creator accounts). This is the creator's current setting, updatable via PATCH /users/me/subscription-price."},"earnings":{"type":"object","properties":{"total":{"type":"number","description":"All-time gross earnings (sum of paid earning invoices), in USD cents"},"availableBalance":{"type":"number","description":"Current available balance that can be withdrawn, in USD cents"},"lastPayoutAt":{"type":["string","null"],"format":"date-time","description":"Date of the most recent payout (paid_at), or null if there has been no payout"}},"required":["total","availableBalance","lastPayoutAt"]},"fans":{"type":"object","properties":{"followers":{"type":"number","description":"Number of contactable followers"},"subscribers":{"type":"number","description":"Number of contactable active subscribers"}},"required":["followers","subscribers"]}},"required":["status","subscriptionPrice","earnings","fans"]}},"required":["uuid","email","handle","displayName","isCreator","createdAt","updatedAt","avatarUrl","bannerUrl","bio","account"]},"example":{"uuid":"3bbe6394-2830-4646-a8ba-4a0a05426947","email":"johnny@fanvue.com","handle":"johnny-doey","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","bio":"Content creator and influencer","account":{"status":"active","subscriptionPrice":999,"earnings":{"total":1532400,"availableBalance":412800,"lastPayoutAt":"2024-11-28T09:00:00.000Z"},"fans":{"followers":3420,"subscribers":890}}}}}},"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"}}}},"/users/me/subscription-price":{"patch":{"summary":"Update subscription price","description":"Set the authenticated creator's monthly subscription price, in USD cents (minor units).\n\n**⚠️ Side effect when increasing the price:** all existing active subscribers are moved to a pending opt-in state for the new price. With `forceOptIn: false` (default) they keep auto-renewing at their current price until they accept the new one; with `forceOptIn: true` they are forced to opt in at the new price and their current auto-renewal is disabled. The response's `subscribersMovedToReOptIn` reports whether this happened. Decreasing the price has no effect on existing subscribers.\n\nThe new price must stay compatible with the creator's promotions: if any promotion's discount would take it below the platform minimum, the request is rejected until that promotion is deleted.","operationId":"updateSubscriptionPrice","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:creator"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionPrice":{"type":"integer","minimum":399,"maximum":10000,"description":"New monthly subscription price in USD cents (minor units), between 399 and 10000"},"forceOptIn":{"type":"boolean","default":false,"description":"Only used when the price increases. When false (default), existing subscribers keep auto-renewing at their current price until they opt in to the new one. When true, they are forced to opt in at the new price and their current auto-renewal is disabled."}},"required":["subscriptionPrice"]}}}},"responses":{"200":{"description":"Subscription price updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionPrice":{"type":"integer","description":"The subscription price now in effect, in USD cents (minor units)"},"subscribersMovedToReOptIn":{"type":"boolean","description":"True when the price increase moved existing active subscribers to a pending re-opt-in state (see the endpoint description)"}},"required":["subscriptionPrice","subscribersMovedToReOptIn"]},"example":{"subscriptionPrice":999,"subscribersMovedToReOptIn":true}}}},"400":{"description":"Invalid price, not a creator account, or conflicting active promotion","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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.","operationId":"createVaultFolder","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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","null"],"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.","operationId":"listVaultFolders","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"integer","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":"integer","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":"Case-insensitive substring match on media name. Returns only folders that contain at least one matching media item."},"required":false,"description":"Case-insensitive substring match on media name. Returns only folders that contain at least one matching media item.","name":"mediaName","in":"query"}],"security":[{"BearerAuth":["read:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"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","null"],"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.","operationId":"getVaultFolder","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"}],"security":[{"BearerAuth":["read:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"responses":{"200":{"description":"Folder details","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Folder name"},"createdAt":{"type":["string","null"],"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.","operationId":"renameVaultFolder","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"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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.","operationId":"deleteVaultFolder","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"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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.","operationId":"listVaultFolderMedia","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":"integer","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":"integer","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","description":"Case-insensitive substring match on the media name."},"required":false,"description":"Case-insensitive substring match on the media name.","name":"name","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter to media created on or after this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-20T00:00:00Z)."},"required":false,"description":"Filter to media created on or after this ISO 8601 datetime (with optional timezone offset, e.g. 2024-10-20T00:00:00Z).","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter to media created before this ISO 8601 datetime (non-inclusive, with optional timezone offset)."},"required":false,"description":"Filter to media created before this ISO 8601 datetime (non-inclusive, with optional timezone offset).","name":"endDate","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},{"schema":{"type":"string","enum":["createdAt","addedAt"],"default":"createdAt","description":"Field to sort media by. Defaults to createdAt (media creation time)."},"required":false,"description":"Field to sort media by. Defaults to createdAt (media creation time).","name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction. Defaults to desc."},"required":false,"description":"Sort direction. Defaults to desc.","name":"order","in":"query"}],"security":[{"BearerAuth":["read:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:media` — Access media files, images, videos, and other content assets.\n</Info>"},"responses":{"200":{"description":"List of media in folder","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","null"],"format":"date"},"url":{"type":"string"},"caption":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"recommendedPrice":{"type":["number","null"]},"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","null"]},"height":{"type":["number","null"]},"lengthMs":{"type":["number","null"]}},"required":["uuid","variantType","displayPosition","width","height","lengthMs"]}},"purchasedByFan":{"type":"boolean"},"tags":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"AI-generated natural language description"},"tags":{"type":"array","items":{"type":"string"},"description":"General content tags"},"nsfwCategory":{"type":"array","items":{"type":"string"},"description":"NSFW classification labels"},"sexActs":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}},"people":{"type":"array","items":{"type":"string"}},"sexObjects":{"type":"array","items":{"type":"string"}},"setting":{"type":"array","items":{"type":"string"},"description":"Scene / environment tags"},"position":{"type":"array","items":{"type":"string"}},"skinColor":{"type":"array","items":{"type":"string"}},"bodyType":{"type":"array","items":{"type":"string"}},"hairColor":{"type":"array","items":{"type":"string"}},"otherTags":{"type":"array","items":{"type":"string"}},"importantTags":{"type":"array","items":{"type":"string"},"description":"Tags the model marked as salient"},"isNsfw":{"type":"boolean"},"mediaType":{"type":"string","enum":["image","video"]}},"required":["description","tags","nsfwCategory","sexActs","bodyParts","people","sexObjects","setting","position","skinColor","bodyType","hairColor","otherTags","importantTags","isNsfw","mediaType"],"description":"Structured AI content tags. Only populated when the owning creator has AI content tagging enabled and the media has been processed; null otherwise."}},"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":"550e8400-e29b-41d4-a716-446655440000","status":"ready","createdAt":"2025-01-15T10:30:00.000Z","caption":null,"description":null,"name":"photo1.jpg","mediaType":"image","recommendedPrice":null,"variants":[{"uuid":"550e8400-e29b-41d4-a716-4466554400aa","variantType":"main","displayPosition":0,"url":"https://media.fanvue.com/main/550e8400-e29b-41d4-a716-446655440000.jpg","width":1920,"height":1440,"lengthMs":null}]},{"uuid":"550e8400-e29b-41d4-a716-446655440001","status":"processing"}],"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.","operationId":"attachMediaToVaultFolder","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"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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}":{"patch":{"summary":"Update media properties","description":"Update properties of a media item within the specified folder.\n\nCurrently supports updating the media `name` and `recommendedPrice`. Include\nonly the fields you want to change; pass `null` to clear a field. The media item\nmust belong to the authenticated user and be present in the folder.","operationId":"updateVaultFolderMedia","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"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"New media name. Pass null to clear it; omit to leave unchanged."},"recommendedPrice":{"type":["integer","null"],"minimum":0,"maximum":50000,"description":"Recommended price in the smallest currency unit (cents). Pass null to clear it; omit to leave unchanged."}}}}}},"responses":{"204":{"description":"Media properties 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"}}},"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.","operationId":"detachMediaFromVaultFolder","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"}],"security":[{"BearerAuth":["write:media"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n</Info>"},"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"}}}},"/webhooks/subscriptions":{"get":{"summary":"List webhook subscriptions","description":"List the authenticated creator's active webhook subscriptions.","operationId":"listWebhookSubscriptions","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"200":{"description":"List of webhook subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Webhook subscription ID"},"url":{"type":"string","description":"Delivery URL for this subscription"},"events":{"type":"array","items":{"type":"string"},"description":"The platform events this subscription delivers"},"createdAt":{"type":"string","format":"date-time","description":"When the subscription was created"}},"required":["id","url","events","createdAt"]}}},"required":["data"]},"example":{"data":[{"id":"d4e5f6g7-8h9i-0j1k-2l3m-n4o5p6q7r8s9","url":"https://hooks.zapier.com/hooks/catch/123456/abcdef","events":["checkout_link.payment.succeeded","checkout_link.subscription.activated"],"createdAt":"2024-01-15T00:00:00.000Z"},{"id":"e5f6g7h8-9i0j-1k2l-3m4n-o5p6q7r8s9t0","url":"https://hooks.zapier.com/hooks/catch/123456/uvwxyz","events":["message.received"],"createdAt":"2024-01-14T00:00:00.000Z"}]}}}},"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 webhook subscription","description":"Subscribe a public HTTPS URL to one or more platform events. Every requested event is delivered to the same URL and signed with the single `signingSecret` returned in the response — store it, as it is only returned at creation time. The token must hold the OAuth scope each requested event needs: `read:creator` for `subscription.new`, `subscription.renewed`, `subscription.cancelled`, `subscription.expired`, `follow.new`, `purchase.new`, `tip.new`, the `checkout_link.*` and `payout.paid` events, and the `creator.payment.succeeded`, `creator.subscription.*`, `creator.refund.created`, and `creator.dispute.*` events; `read:post` for `creator.post.liked` and `creator.post.commented`; `read:chat` for `message.received`, `message.read`, `creator.message.received`, `creator.message.sent`, `creator.message.read`, `creator.message.read_by_fan`, `creator.message.reaction`, and `creator.message.deleted`.\n\nThe two read receipts are separate directions and neither replaces the other: `creator.message.read` fires when the creator reads the fan's messages, `creator.message.read_by_fan` when the fan reads the creator's. Their topic names the actor while the `object` in the payload (`fan_message_read` / `creator_message_read`) names whose messages were read, so the two names run on different axes.","operationId":"createWebhookSubscription","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public HTTPS URL the event payloads are delivered to (no redirects, no localhost)"},"events":{"type":"array","items":{"type":"string","enum":["checkout_link.payment.pending","checkout_link.payment.succeeded","checkout_link.payment.failed","checkout_link.subscription.activated","checkout_link.subscription.deactivated","checkout_link.subscription.cancel_at_period_end_changed","checkout_link.refund.created","checkout_link.dispute.flagged","checkout_link.dispute.created","checkout_link.installment.paid","checkout_link.installment.failed","checkout_link.plan.completed","payout.paid","payout.failed","follow.new","message.read","message.received","purchase.new","subscription.new","subscription.renewed","subscription.cancelled","subscription.expired","tip.new","creator.payment.succeeded","creator.subscription.activated","creator.subscription.renewed","creator.subscription.deactivated","creator.subscription.cancel_at_period_end_changed","creator.post.liked","creator.post.commented","creator.message.reaction","creator.message.deleted","creator.refund.created","creator.dispute.flagged","creator.dispute.created","creator.reward.created","creator.reward.reversed","creator.fan.status_changed","creator.fan.presence_changed","creator.follow.created","creator.message.received","creator.message.sent","creator.message.read","creator.message.read_by_fan"],"description":"The platform event the webhook subscription delivers"},"minItems":1,"description":"One or more platform events this subscription delivers"}},"required":["url","events"]}}}},"responses":{"201":{"description":"Webhook subscription created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"ID of the created webhook subscription"},"signingSecret":{"type":"string","description":"HMAC signing secret for verifying delivery signatures. Returned only on creation — store it securely now."}},"required":["id","signingSecret"]},"example":{"id":"d4e5f6g7-8h9i-0j1k-2l3m-n4o5p6q7r8s9","signingSecret":"whsec_3b1f8a0c2d4e6f8091a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f708"}}}},"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"}}}},"/webhooks/subscriptions/{id}":{"delete":{"summary":"Delete a webhook subscription","description":"Delete a webhook subscription owned by the authenticated creator.","operationId":"deleteWebhookSubscription","parameters":[{"$ref":"#/components/parameters/ApiVersionHeader"},{"schema":{"type":"string","format":"uuid","description":"Webhook subscription ID"},"required":true,"description":"Webhook subscription ID","name":"id","in":"path"}],"security":[{"BearerAuth":["read:self"]}],"x-mint":{"content":"<Info>\n  **Required scope**\n\n  - `read:self` — Access your own user profile information, including basic account details and settings.\n</Info>"},"responses":{"204":{"description":"Webhook subscription 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"}}}}},"webhooks":{}}