{
"openapi": "3.1.0",
"info": {
"title": "Fanvue API",
"version": "0.1"
},
"servers": [
{
"url": "https://api.fanvue.com"
}
],
"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"
},
"IdempotencyKeyHeader": {
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"maxLength": 255
},
"description": "Opaque key that makes a send safe to retry. A mass send can take longer than the request timeout, and the campaign is already committed by then, so retrying without a key can deliver the broadcast twice. Reuse the same key on a retry: the original result is replayed once the first attempt finished, and a retry while it is still running is rejected with 409 rather than starting a second send. A key reused for a different message is rejected with 409 too, so pick a new one per send. Keys are scoped to your app and the sending creator, and are remembered for 24 hours."
}
},
"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": "What produced this earning.\n\n`renewal` is a catch-all for every recurring charge after the first payment: profile subscriptions, checkout-link subscriptions and fan-experience subscriptions all bill as `renewal` from their second charge onwards. So `subscription`, `checkoutLink` and `fanExperience` only ever hold first payments and one-off purchases. `appStore` is the single exception: an app's recurring charges stay `appStore`.\n\n`fanExperience` and `appStore` are different sides of a third-party app: `fanExperience` is the creator selling a paid experience to a fan, `appStore` is the app's developer selling to the creator, so an `appStore` row is not fan-to-creator spend. `referral`, `affiliate` and `giveaway` are creator rewards rather than fan purchases. `user` follows the invoice rather than the source: it is null when the row records no fan, the common case for those three, and a `giveaway` granted to a specific fan returns that fan.\n\nReversals 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": {
"/v1/agencies/team-members": {
"get": {
"summary": "List team members",
"description": "Get a list of all team members in the authenticated user's agency.\nRequires: Agency admin access",
"operationId": "listTeamMembers",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:agency"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:agency` — Read agency information, including the agency's team members.\n"
},
"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"
}
}
}
},
"/v1/agencies/team-members/{userId}": {
"put": {
"summary": "Update team member",
"description": "Update a team member's properties such as admin status or nickname.\nRequires: Agency admin access",
"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": "\n **Required scope**\n\n - `write:agency` — Manage agency team members and invites, including inviting new team members and creators.\n"
},
"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"
}
}
}
},
"/v1/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.\nRequires: Agency admin access",
"operationId": "createAgencyInvite",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"write:agency"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `write:agency` — Manage agency team members and invites, including inviting new team members and creators.\n"
},
"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"
}
}
}
},
"/v1/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.\nRequires: Agency admin access",
"operationId": "createCreatorInvite",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"write:agency"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `write:agency` — Manage agency team members and invites, including inviting new team members and creators.\n"
},
"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"
}
}
}
},
"/v1/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\nRequires: `write:post` and `write:creator` scopes, plus access to each creator (agency assignment/admin, or self).",
"operationId": "bulkCreateAgencyPosts",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"write:post",
"write:creator"
]
}
],
"x-mint": {
"content": "\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"
},
"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"
}
}
}
},
"/v1/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.\nRequires: Agency admin access",
"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": "\n **Required scope**\n\n - `read:agency` — Read agency information, including the agency's team members.\n"
},
"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"
}
}
}
},
"/v1/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\n`totalEarnings`, `newFans` and `arpu` are served from the daily warehouse export for the whole UTC days inside the range and read live for the current day and for any partial day at either edge, so they include today. The live reads differ by metric: `totalEarnings` and `arpu` come from invoices, while `newFans` counts a fan's first follow or first subscribe to a creator, so it moves on a free follow or a free trial with no payment behind it. `retention` and `averageFanLifetime` have no live branch and come only from the warehouse snapshots. All money is USD cents; rates are fractions, not percentages.\n\nAlmost every money figure comes as a pair: `gross` is pre-fee earnings, `net` is the creators' cut after platform fees. That is the only axis the two words describe here. Reversals are already handled on both, as each field states. The exception is the `retention` snapshot: `cohortGrossRevenue` and `retainedGrossRevenue` are gross-only with no net counterpart, so `revenueRetentionRate` is a gross-on-gross ratio and there is no net retention figure to select.\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 no fan paid for, such as referrals. `arpu` measures what payers paid, so it drops those and subtracts reversals; the one payer that is not a fan is an App Store invoice, which records a creator buying an app from its developer and is counted by the live branch. Note that this is stricter than the creator-level `/insights/top-spenders`, which counts positive invoices only and so leaves a refunded purchase in at full value. 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.\nRequires: Agency admin access",
"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": "\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"
},
"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 no fan paid for (referrals, affiliate) is excluded, and reversals are subtracted. The one payer that is not a fan is an App Store invoice, which records a creator buying an app from its developer and is counted by the live branch. Subtracting reversals is stricter than the creator-level `/insights/top-spenders`: that endpoint counts positive invoices only, so it leaves a refunded purchase in at full value. 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"
}
}
}
},
"/v1/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\nEvery row carries both figures: `gross` is what payers from that country paid, `net` is the creators' cut after platform fees. Both are already net of refunds and chargebacks, so either can be negative for a country whose only activity in the range was a reversal.\n\nThe payer is not always a fan: an App Store invoice records a creator buying an app from its developer, and the live branch that serves the current day and either partial edge day counts it, so a country's figures can include creator-to-developer spend.\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`.\nRequires: Agency admin access",
"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": "\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"
},
"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 payers from this country who spent in the range. Usually fans; an App Store purchase counts its buyer, who is a creator."
},
"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"
}
}
}
},
"/v1/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, served from the daily warehouse export for the whole UTC days inside the range and read live from invoices for the current day and either partial edge day.\n\nEvery row carries both figures: `gross` is what the payer paid, `net` is the creators' cut after platform fees. Both are already net of refunds and chargebacks, which is stricter than the creator-level `/insights/top-spenders`. The payer is not always a fan: as on `/agencies/insights/demographics`, the live branch counts an App Store invoice, which records a creator buying an app from its developer.\nRequires: Agency admin access",
"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": "\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"
},
"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"
}
}
}
},
"/v1/agencies/chats": {
"get": {
"summary": "List chats across all agency creators (cursor-paginated, filterable)",
"description": "Cursor-paginated stream of chats across every creator the authenticated agency manages, with full filter parity to the creator-self `GET /chats`. Each row is tagged with `creatorUuid`.\n\nEvery filter is correlated to the chat's own creator: `filter=subscribers` returns chats whose counterpart is a subscriber of *that chat's* creator, not of any agency creator.\n\nDesigned for incremental sync: pass `updatedAfter` (and walk `asc`) to pull only chats that changed since the last sync, then page with the opaque `nextCursor`. For the default recency sort the cursor is a keyset position, so deep pages cost the same as the first and a page is never shifted by chats added or removed above it — unlike offset paging. It is not a snapshot: the position is `lastMessageAt`, which moves when a chat receives activity, so a chat can still be missed (walking `desc`, it moves above a cursor already passed) or returned twice (walking `asc`, it moves below one). Deduplicate by `creatorUuid` + `user.uuid` if you need exactly-once. A cursor is only valid for the `sortBy` and `sortDirection` it was minted under; reusing it under different sorting returns 400.\n\nSupported `filter[]` values: 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. Per-creator list filters (customListId, smartListIds) are intentionally omitted — they have no meaning in a cross-creator aggregate.\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`sortBy` composes with `search`, `filter` and `updatedAfter`. `online_now` and `most_unanswered_chats` rank on live values with no stable position to resume from, so their pages are addressed by an offset carried inside the same opaque cursor: a chat whose presence or unread count changes mid-traversal can be repeated or passed by. Re-request the first page for a fresh ranking.\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)\nRequires: Agency admin access",
"operationId": "listAgencyChatsV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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": "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",
"maxLength": 100,
"description": "Search term to filter chats by counterpart name or handle"
},
"required": false,
"description": "Search term to filter chats by counterpart name or handle",
"name": "search",
"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, correlated to each chat's own creator (repeat the param for multiple)"
},
"required": false,
"description": "Filter types to apply, correlated to each chat's own creator (repeat the param for multiple)",
"name": "filter",
"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: `desc` (highest-ranked first, default) or `asc` (reversed, for backfills)"
},
"required": false,
"description": "Sort direction: `desc` (highest-ranked first, default) or `asc` (reversed, for backfills)",
"name": "sortDirection",
"in": "query"
}
],
"security": [
{
"BearerAuth": [
"read:agency",
"read:chat"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-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, in the requested sort order"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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
}
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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\nMaximum 50 chat UUIDs in total across all creators, and 25 creators per request.\nRead-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.\nRequires: Agency admin access",
"operationId": "batchAgencyMessages",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:agency",
"read:chat"
]
}
],
"x-mint": {
"content": "\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"
},
"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 ![]()
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"
}
}
}
},
"/v1/agencies/subscribers": {
"get": {
"summary": "List active subscribers across all agency creators (cursor-paginated)",
"description": "Cursor-paginated stream of active subscriptions across every creator the authenticated agency manages, most recent first. Each row is tagged with `creatorUuid`.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent subscription changes, unlike the offset-paginated v0 endpoint.\nRequires: Agency admin access",
"operationId": "listAgencySubscribers_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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": "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": "\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"
},
"responses": {
"200": {
"description": "Cursor-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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/agencies/earnings": {
"get": {
"summary": "List per-creator-per-day earnings across all agency creators (cursor-paginated)",
"description": "Returns a single cursor-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\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`.\nRequires: Agency admin access",
"operationId": "listAgencyEarningsByDayV1",
"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)",
"name": "creatorUuids",
"in": "query",
"style": "form",
"explode": false
}
],
"security": [
{
"BearerAuth": [
"read:agency",
"read:creator"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-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"
},
"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": [
{
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"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"
}
}
}
},
"/v1/agencies/subscribers-history": {
"get": {
"summary": "List per-creator-per-day subscriber events across all agency creators (cursor-paginated)",
"description": "Returns a single cursor-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` (on each row) = 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\nPage with the opaque `nextCursor` from the previous response. The result set is bounded by the requested date range, so the envelope's `total` is not computed and is always `null` (distinct from each row's per-creator `total` field).\n\nIf you need the current list of subscribers for messaging or CRM sync, use `GET /agencies/subscribers` instead.\nRequires: Agency admin access",
"operationId": "listAgencySubscribersHistoryV1",
"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. 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": "\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"
},
"responses": {
"200": {
"description": "Cursor-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"
},
"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": [
{
"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
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"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"
}
}
}
},
"/v1/agencies/followers-history": {
"get": {
"summary": "List per-creator-per-day new-follower counts across all agency creators (cursor-paginated)",
"description": "Returns a single cursor-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` (on each row) = cumulative new followers for the creator from the beginning of the requested range (running sum of `newFollowersCount`)\n\nFollows 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). Each row's `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.\n\nPage with the opaque `nextCursor` from the previous response. The result set is bounded by the requested date range, so the envelope's `total` is not computed and is always `null` (distinct from each row's per-creator `total` field).\n\nRequires: Agency admin access",
"operationId": "listAgencyFollowersHistoryV1",
"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. 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": "\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"
},
"responses": {
"200": {
"description": "Cursor-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"
},
"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": [
{
"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
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"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"
}
}
}
},
"/v1/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": "\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"
},
"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 (cursor-paginated)",
"description": "Cursor-paginated list of chat conversations with optional filtering, searching, and sorting. Page with the opaque `nextCursor` from the previous response.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to cursor pagination. For the default recency sort the cursor is a keyset position, so deep pages cost the same as the first and rows are never repeated or shifted past as chats arrive — unlike offset paging. Note that the sort key is live activity: a chat that receives a message mid-traversal moves to the front of the order, so a long walk can pass it by. Re-request the first page to pick up newly active chats. A cursor is only valid for the `sortBy` and `sortDirection` it was minted under; reusing it under different sorting returns 400.\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- `archived` - Only archived 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\nSome filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.",
"operationId": "listChats_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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": "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"
},
"description": "Filter chats to these counterpart (fan) user UUIDs (repeat the param for multiple)"
},
"required": false,
"description": "Filter chats to these counterpart (fan) user UUIDs (repeat the param for multiple)",
"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": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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"
}
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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": {
"description": "Some filters are only available to creators",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"410": {
"$ref": "#/components/responses/SunsetVersionResponse"
},
"429": {
"$ref": "#/components/responses/RateLimitResponse"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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"
},
{
"$ref": "#/components/parameters/IdempotencyKeyHeader"
}
],
"security": [
{
"BearerAuth": [
"write:chat",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"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"
},
"409": {
"description": "The Idempotency-Key conflicts with another send: either the first one is still in progress, or the key was already used for a different message",
"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 mass messages (cursor-paginated)",
"description": "Cursor-paginated list of the creator's mass (broadcast) messages, most recent first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent sends, unlike the offset-paginated v0 endpoint.\nRequires: Creator account",
"operationId": "listMassMessages_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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",
"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": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated list of mass messages",
"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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"example": {
"data": [
{
"uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
"text": "Big news for my subscribers ❤️",
"status": "SENT",
"price": 500,
"createdAt": "2024-01-15T00:00:00.000Z",
"publishedAt": "2024-01-15T00:00:00.000Z",
"scheduledAt": null,
"recipientCount": 1200,
"viewCount": 830,
"purchaseCount": 145,
"totalRevenue": 72500,
"mediaUuids": [
"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
],
"includedLists": {
"smartListIds": [
"subscribers"
],
"smartListUuids": [
"subscribers"
],
"customListUuids": []
},
"excludedLists": {
"smartListIds": [],
"smartListUuids": [],
"customListUuids": []
}
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": {
"description": "This endpoint is only available to creators",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"410": {
"$ref": "#/components/responses/SunsetVersionResponse"
},
"429": {
"$ref": "#/components/responses/RateLimitResponse"
}
}
}
},
"/v1/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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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 ![]()
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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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"
}
}
}
},
"/v1/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\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",
"operationId": "getUnreadChatsCount",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:chat"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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"
}
}
}
},
"/v1/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\nMaximum 100 user UUIDs per request. Users who have disabled online visibility will always appear as offline with no last seen timestamp.",
"operationId": "getBatchStatuses",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:chat"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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"
}
}
}
},
"/v1/chats/{userUuid}/messages": {
"get": {
"summary": "Get messages from a chat",
"description": "Returns a date-based list of text messages between the authenticated user and the specified user. Messages are ordered by date (newest first).\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to date-based pagination with separate filters for sent and received messages.\n\n**Pagination Flow:**\n- First request: No date filters needed, returns first 20 messages (or specified limit)\n- Subsequent requests: Use the date filters from the previous response\n- End of results: date filters will be `null`\n\n**Partial Filters Supported:**\nYou can provide:\n- Both `sentBefore` and `receivedBefore` for standard pagination\n- Only `sentBefore` to filter messages sent by the user\n- Only `receivedBefore` to filter messages received from the user\n- Neither filter for the first request\n\n**Date Filter Structure:**\nThe response contains two date filters:\n```json\n{\n // Date filter for messages sent by user (use for next request)\n \"sentBefore\": \"2024-01-10T12:00:00Z\",\n // Date filter for messages received by user (use for next request)\n \"receivedBefore\": \"2024-01-10T11:00:00Z\"\n}\n```\n\nBoth filters can be `null` if messages only flow in one direction.\n\n\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",
"operationId": "listMessages_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "userUuid",
"in": "path"
},
{
"schema": {
"type": [
"string",
"null"
],
"format": "date",
"description": "Fetch messages sent before this date"
},
"required": false,
"description": "Fetch messages sent before this date",
"name": "sentBefore",
"in": "query"
},
{
"schema": {
"type": [
"string",
"null"
],
"format": "date",
"description": "Fetch messages received before this date"
},
"required": false,
"description": "Fetch messages received before this date",
"name": "receivedBefore",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 50,
"default": 20,
"description": "Number of messages to return (1-50, default: 20)"
},
"required": false,
"description": "Number of messages to return (1-50, default: 20)",
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false",
"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:chat"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"responses": {
"200": {
"description": "Date-based 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"
]
},
"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 ![]()
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. `text` may be set alongside it — a GIF can be sent with a caption."
},
"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"
}
},
"required": [
"uuid",
"handle"
]
},
"type": {
"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"
]
},
"status": {
"type": "string",
"enum": [
"SENT",
"UNSENT",
"MODERATED"
]
},
"isRead": {
"type": "boolean"
},
"isSubscribed": {
"type": "boolean"
},
"isFollowing": {
"type": "boolean"
},
"followForFreeEnabled": {
"type": "boolean"
},
"repliedMessage": {
"type": [
"object",
"null"
],
"properties": {
"parent_message_id": {
"type": "number"
},
"child_message_id": {
"type": "number"
},
"parent_message": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
},
"id": {
"type": "number"
},
"text": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date"
},
"published_at": {
"type": [
"string",
"null"
],
"format": "date"
},
"owner_id": {
"type": "number"
},
"recipient_id": {
"type": [
"number",
"null"
]
},
"price": {
"type": [
"number",
"null"
]
},
"publish_at": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"SENT",
"UNSENT",
"MODERATED"
]
},
"type": {
"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"
]
},
"sender": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"is_creator": {
"type": "boolean"
},
"handle": {
"type": "string"
}
},
"required": [
"id",
"uuid",
"is_creator",
"handle"
]
}
},
"required": [
"uuid",
"id",
"text",
"created_at",
"published_at",
"owner_id",
"recipient_id",
"price",
"publish_at",
"status",
"type",
"sender"
]
}
},
"required": [
"parent_message_id",
"child_message_id",
"parent_message"
]
},
"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."
}
},
"required": [
"uuid",
"text",
"gif",
"sentAt",
"sender",
"recipient",
"type",
"status",
"isRead",
"isSubscribed",
"isFollowing",
"followForFreeEnabled",
"repliedMessage",
"sentByUserId",
"appUuid"
]
}
},
"dateFilter": {
"type": [
"object",
"null"
],
"properties": {
"sentBefore": {
"type": [
"string",
"null"
],
"format": "date"
},
"receivedBefore": {
"type": [
"string",
"null"
],
"format": "date"
}
},
"required": [
"sentBefore",
"receivedBefore"
],
"description": "Next date filters, null if no more results"
}
},
"required": [
"data",
"dateFilter"
]
},
"example": {
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"text": "Hey there! How are you doing?",
"gif": null,
"sentAt": "2024-01-10T12:00:00.000Z",
"sender": {
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"handle": "sarah"
},
"recipient": {
"uuid": "550e8400-e29b-41d4-a716-446655440002",
"handle": "johnny"
},
"type": "TEXT",
"status": "SENT",
"isRead": true,
"isSubscribed": true,
"isFollowing": false,
"followForFreeEnabled": false,
"repliedMessage": null,
"sentByUserId": null,
"appUuid": "f6a7b8c9-0123-4567-89ab-cdef01234567"
},
{
"uuid": "660e8400-e29b-41d4-a716-446655440001",
"text": "I'm doing great! Thanks for asking.",
"gif": null,
"sentAt": "2024-01-10T11:59:00.000Z",
"sender": {
"uuid": "550e8400-e29b-41d4-a716-446655440002",
"handle": "johnny"
},
"recipient": {
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"handle": "sarah"
},
"type": "TEXT",
"status": "SENT",
"isRead": true,
"isSubscribed": true,
"isFollowing": false,
"followForFreeEnabled": false,
"repliedMessage": null,
"sentByUserId": null,
"appUuid": null
},
{
"uuid": "770e8400-e29b-41d4-a716-446655440002",
"text": 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
},
"sentAt": "2024-01-10T11:58:00.000Z",
"sender": {
"uuid": "550e8400-e29b-41d4-a716-446655440002",
"handle": "johnny"
},
"recipient": {
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"handle": "sarah"
},
"type": "TEXT",
"status": "SENT",
"isRead": true,
"isSubscribed": true,
"isFollowing": false,
"followForFreeEnabled": false,
"repliedMessage": null,
"sentByUserId": null,
"appUuid": null
}
],
"dateFilter": {
"sentBefore": "2024-01-10T12:00:00.000Z",
"receivedBefore": "2024-01-10T11:59: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": {
"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"
}
}
}
},
"/v1/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\nMaximum 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.\n\nRead-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.",
"operationId": "messagesBatch",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:chat"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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 ![]()
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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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"
}
}
}
},
"/v1/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\nThe `mediaUuids` query parameter is required and accepts up to 20 UUIDs.",
"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": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/chats/lists/smart/{uuid}": {
"get": {
"summary": "Get smart list members (cursor-paginated)",
"description": "Get members of a specific smart list. Smart lists are system-generated dynamic audience segments (not user-created lists). The returned members are filtered by contactability and the selected smart list type.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to an opaque `cursor`. Page with the `nextCursor` from the previous response and keep `size` constant for the whole walk. `total` is not computed for this list and is always `null`.",
"operationId": "getSmartListMembersV1",
"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": "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"
}
],
"security": [
{
"BearerAuth": [
"read:chat",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"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": [
{
"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
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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"
}
}
}
},
"/v1/chats/lists/custom": {
"get": {
"summary": "Get custom lists (cursor-paginated)",
"description": "Get user's custom lists with member counts. Supports optional name search and cursor pagination — page with the opaque `nextCursor` from the previous response. `total` is not computed for this list and is always `null`.",
"operationId": "getCustomListsV1",
"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",
"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": "\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"
},
"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"
},
"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": [
{
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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"
}
}
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/chats/lists/custom/{uuid}": {
"get": {
"summary": "Get custom list members (cursor-paginated)",
"description": "Cursor-paginated list of a custom list's members, most recently added first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable while members are added or removed, unlike the offset-paginated v0 endpoint.",
"operationId": "getCustomListMembers_v1_experimental",
"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",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:chat",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated list of 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": "Array of list members, most recently added first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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": {
"description": "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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/chats/templates": {
"get": {
"summary": "Get list of template messages (cursor-paginated)",
"description": "Returns a cursor-paginated list of template messages. Optionally filter by folder name using case-insensitive partial matching. Page with the opaque `nextCursor` from the previous response. `total` is not computed for this list and is always `null`.",
"operationId": "listTemplateMessagesV1",
"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",
"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": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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"
},
"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": [
{
"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
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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"
}
}
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/chats/templates/folders": {
"get": {
"summary": "Get list of template folders (cursor-paginated)",
"description": "Returns a cursor-paginated list of the creator's template folders. Use a folder UUID when creating a template with POST /chats/templates. Page with the opaque `nextCursor` from the previous response. `total` is not computed for this list and is always `null`.",
"operationId": "listTemplateFoldersV1",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:chat"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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"
},
"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": [
{
"uuid": "b0a1c2d3-e4f5-6789-abcd-ef0123456789",
"name": "Welcome Messages"
},
{
"uuid": "c1b2a3d4-f5e6-7890-bcde-f01234567890",
"name": "Promotions"
}
],
"nextCursor": null,
"total": 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"
}
}
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:chat` — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.\n"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/checkout-links": {
"get": {
"summary": "List checkout links (cursor-paginated)",
"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).\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent writes, unlike the offset-paginated v0 endpoint.",
"operationId": "listCheckoutLinks_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/collections": {
"get": {
"summary": "List content collections (cursor-paginated)",
"description": "Returns a cursor-paginated list of the authenticated creator's content collections, newest first. Keyset pagination is stable under concurrent writes and has constant per-page cost, unlike the offset-paginated v0 endpoint. Page with the opaque `nextCursor`.",
"operationId": "listCollectionsV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:post"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:post` — Read posts, including post details, comments, likes, and tips.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, newest first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"example": {
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"label": "Behind the scenes",
"createdAt": "2025-01-16T14:20:00.000Z"
},
{
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"label": "Promos",
"createdAt": "2025-01-15T10:30:00.000Z"
}
],
"nextCursor": "k0FQ1m9yb3ZpZGVkQnlUaGVBUEk",
"total": 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"
},
"503": {
"description": "Upstream collections service is unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
}
}
},
"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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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"
]
}
}
}
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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"
]
}
}
}
}
}
}
},
"/v1/creators": {
"get": {
"summary": "Get agency creators (cursor-paginated)",
"description": "Returns the creators the authenticated agency user's seat is assigned to. Owner seats see every creator on the organization's roster; other seats see only the creators explicitly assigned to them.\n\nReturns 403 when the authenticated account holds no agency team-member seat, so an empty list always means the seat has no assigned creators rather than the token not being an agency one.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to an opaque `cursor`. Page with the `nextCursor` from the previous response and nothing else: the cursor carries the page size the walk started on, so `size` does not need resending. Resending it is allowed while it matches; a different value is rejected with a `400`, because this list is addressed by page and a new size would re-anchor the page boundary. `total` is not computed for this list and is always `null`.",
"operationId": "listCreatorsV1",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"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": [
{
"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"
}
],
"nextCursor": null,
"total": 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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/followers": {
"get": {
"summary": "Get creator followers (cursor-paginated)",
"description": "Returns the users who follow the specified creator, most recently followed first.\n\nA fan who both follows and holds an active subscription appears in this list as well as in the subscribers list, so the two are not disjoint — de-duplicate on the user `uuid` if you merge them.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent follows, unlike the offset-paginated v0 endpoint.",
"operationId": "listCreatorFollowersV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recently followed first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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"
},
"likesCount": {
"type": "number",
"description": "Total likes the creator's content has received. Absent for non-creator accounts."
},
"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"
],
"description": "Counts of the creator's posted content by media type. Absent for non-creator accounts."
},
"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",
"likesCount": 1250,
"contentCounts": {
"imageCount": 145,
"videoCount": 67,
"audioCount": 12,
"postCount": 234,
"payToViewPostCount": 45
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/subscribers": {
"get": {
"summary": "Get creator subscribers (cursor-paginated)",
"description": "Returns the users subscribed to the specified creator.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination for both sort modes. The v0 endpoint accepted `page` and `cursor` side by side; here `page` is gone. Page with the opaque `nextCursor`.",
"operationId": "listCreatorSubscribersV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"enum": [
"name",
"subscribedAt"
],
"description": "Public field to sort by (default: subscribedAt)"
},
"required": false,
"description": "Public field to sort by (default: subscribedAt)",
"name": "sortField",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort direction (default: desc for subscribedAt, asc for name)"
},
"required": false,
"description": "Sort direction (default: desc for subscribedAt, asc for name)",
"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 `nextCursor`. It carries the sortField, sortDirection and date range the first page was cut under, so later pages need nothing but the cursor. Resending those filters is allowed while they match it; a value that contradicts the cursor is rejected."
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`. It carries the sortField, sortDirection and date range the first page was cut under, so later pages need nothing but the cursor. Resending those filters is allowed while they match it; a value that contradicts the cursor is rejected.",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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 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"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/chats": {
"get": {
"summary": "Get chats of a creator (cursor-paginated)",
"description": "Returns a cursor-paginated list of chats for the specified creator, most recent activity first. Keyset pagination is stable under concurrent messages and has constant per-page cost, unlike the offset-paginated v0 endpoint. Page with the opaque `nextCursor`.",
"operationId": "listCreatorChatsV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:chat"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recent activity first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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"
}
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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"
}
}
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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"
},
{
"$ref": "#/components/parameters/IdempotencyKeyHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
}
],
"security": [
{
"BearerAuth": [
"write:chat",
"read:creator",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"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"
},
"409": {
"description": "The Idempotency-Key conflicts with another send: either the first one is still in progress, or the key was already used for a different message",
"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 mass messages for a creator (cursor-paginated)",
"description": "Returns a cursor-paginated list of mass (broadcast) messages sent by the specified creator, most recent first, 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**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent sends, unlike the offset-paginated v0 endpoint.",
"operationId": "listCreatorMassMessagesV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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",
"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": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"example": {
"data": [
{
"uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
"text": "Big news for my subscribers ❤️",
"status": "SENT",
"price": 500,
"createdAt": "2024-01-15T00:00:00.000Z",
"publishedAt": "2024-01-15T00:00:00.000Z",
"scheduledAt": null,
"recipientCount": 1200,
"viewCount": 830,
"purchaseCount": 145,
"totalRevenue": 72500,
"mediaUuids": [
"a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
],
"includedLists": {
"smartListIds": [
"subscribers"
],
"smartListUuids": [
"subscribers"
],
"customListUuids": []
},
"excludedLists": {
"smartListIds": [],
"smartListUuids": [],
"customListUuids": []
}
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/chats/{userUuid}/messages": {
"get": {
"summary": "Get messages between a creator and a user",
"description": "Returns a date-based list of text messages between the specified creator and user, ordered by date (newest first).\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to date-based pagination with separate filters for sent and received messages, matching `GET /chats/{userUuid}/messages`.\n\n**Pagination Flow:**\n- First request: No date filters needed, returns first 20 messages (or specified limit)\n- Subsequent requests: Use the date filters from the previous response\n- End of results: date filters will be `null`\n\n**Partial Filters Supported:**\nYou can provide:\n- Both `sentBefore` and `receivedBefore` for standard pagination\n- Only `sentBefore` to filter messages sent by the creator\n- Only `receivedBefore` to filter messages received from the user\n- Neither filter for the first request\n\n**Also breaking**: `markAsRead` now defaults to `false`, so reading a conversation no longer mutates its read state. Pass `markAsRead=true` to keep the v0 behaviour.",
"operationId": "listCreatorMessagesV1",
"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",
"null"
],
"format": "date",
"description": "Fetch messages sent before this date"
},
"required": false,
"description": "Fetch messages sent before this date",
"name": "sentBefore",
"in": "query"
},
{
"schema": {
"type": [
"string",
"null"
],
"format": "date",
"description": "Fetch messages received before this date"
},
"required": false,
"description": "Fetch messages received before this date",
"name": "receivedBefore",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 50,
"default": 20,
"description": "Number of messages to return (1-50, default: 20)"
},
"required": false,
"description": "Number of messages to return (1-50, default: 20)",
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false",
"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": "\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"
},
"responses": {
"200": {
"description": "Date-based 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"
]
},
"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 ![]()
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. `text` may be set alongside it — a GIF can be sent with a caption."
},
"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"
}
},
"required": [
"uuid",
"handle"
]
},
"type": {
"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"
]
},
"status": {
"type": "string",
"enum": [
"SENT",
"UNSENT",
"MODERATED"
]
},
"isRead": {
"type": "boolean"
},
"isSubscribed": {
"type": "boolean"
},
"isFollowing": {
"type": "boolean"
},
"followForFreeEnabled": {
"type": "boolean"
},
"repliedMessage": {
"type": [
"object",
"null"
],
"properties": {
"parent_message_id": {
"type": "number"
},
"child_message_id": {
"type": "number"
},
"parent_message": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
},
"id": {
"type": "number"
},
"text": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date"
},
"published_at": {
"type": [
"string",
"null"
],
"format": "date"
},
"owner_id": {
"type": "number"
},
"recipient_id": {
"type": [
"number",
"null"
]
},
"price": {
"type": [
"number",
"null"
]
},
"publish_at": {
"type": [
"string",
"null"
],
"format": "date"
},
"status": {
"type": "string",
"enum": [
"SENT",
"UNSENT",
"MODERATED"
]
},
"type": {
"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"
]
},
"sender": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"is_creator": {
"type": "boolean"
},
"handle": {
"type": "string"
}
},
"required": [
"id",
"uuid",
"is_creator",
"handle"
]
}
},
"required": [
"uuid",
"id",
"text",
"created_at",
"published_at",
"owner_id",
"recipient_id",
"price",
"publish_at",
"status",
"type",
"sender"
]
}
},
"required": [
"parent_message_id",
"child_message_id",
"parent_message"
]
},
"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."
}
},
"required": [
"uuid",
"text",
"gif",
"sentAt",
"sender",
"recipient",
"type",
"status",
"isRead",
"isSubscribed",
"isFollowing",
"followForFreeEnabled",
"repliedMessage",
"sentByUserId",
"appUuid"
]
}
},
"dateFilter": {
"type": [
"object",
"null"
],
"properties": {
"sentBefore": {
"type": [
"string",
"null"
],
"format": "date"
},
"receivedBefore": {
"type": [
"string",
"null"
],
"format": "date"
}
},
"required": [
"sentBefore",
"receivedBefore"
],
"description": "Next date filters, null if no more results"
}
},
"required": [
"data",
"dateFilter"
]
},
"example": {
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"text": "Hey there! How are you doing?",
"gif": null,
"sentAt": "2024-01-10T12:00:00.000Z",
"sender": {
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"handle": "sarah"
},
"recipient": {
"uuid": "550e8400-e29b-41d4-a716-446655440002",
"handle": "johnny"
},
"type": "TEXT",
"status": "SENT",
"isRead": true,
"isSubscribed": true,
"isFollowing": false,
"followForFreeEnabled": false,
"repliedMessage": null,
"sentByUserId": null,
"appUuid": "f6a7b8c9-0123-4567-89ab-cdef01234567"
},
{
"uuid": "660e8400-e29b-41d4-a716-446655440001",
"text": "I'm doing great! Thanks for asking.",
"gif": null,
"sentAt": "2024-01-10T11:59:00.000Z",
"sender": {
"uuid": "550e8400-e29b-41d4-a716-446655440002",
"handle": "johnny"
},
"recipient": {
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"handle": "sarah"
},
"type": "TEXT",
"status": "SENT",
"isRead": true,
"isSubscribed": true,
"isFollowing": false,
"followForFreeEnabled": false,
"repliedMessage": null,
"sentByUserId": null,
"appUuid": null
},
{
"uuid": "770e8400-e29b-41d4-a716-446655440002",
"text": 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
},
"sentAt": "2024-01-10T11:58:00.000Z",
"sender": {
"uuid": "550e8400-e29b-41d4-a716-446655440002",
"handle": "johnny"
},
"recipient": {
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"handle": "sarah"
},
"type": "TEXT",
"status": "SENT",
"isRead": true,
"isSubscribed": true,
"isFollowing": false,
"followForFreeEnabled": false,
"repliedMessage": null,
"sentByUserId": null,
"appUuid": null
}
],
"dateFilter": {
"sentBefore": "2024-01-10T12:00:00.000Z",
"receivedBefore": "2024-01-10T11:59: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": {
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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\nThe `mediaUuids` query parameter is required and accepts up to 20 UUIDs.",
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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\nMaximum 100 user UUIDs per request. Users who have disabled online visibility will always appear as offline with no last seen timestamp.",
"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": "\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"
},
"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"
}
}
}
},
"/v1/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\nMaximum 50 chat UUIDs per request. Failed keys are reported as `{ \"error\": \"not_found\" }`.\n\nRead-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.",
"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": "\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"
},
"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 ![]()
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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/media": {
"get": {
"summary": "Get creator's media list (cursor-paginated)",
"description": "Returns a cursor-paginated list of media items for the specified creator, most recent first.\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**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination, and dropped `pagination.total` — a count is the expensive query keyset pagination avoids. Page with the opaque `nextCursor`.",
"operationId": "getCreatorMediaV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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",
"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": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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\nMaximum 20 media UUIDs per request.",
"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": "\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"
},
"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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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"
}
}
}
},
"/v1/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 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.",
"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": "\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"
},
"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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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 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.",
"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": "\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"
},
"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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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"
}
}
}
},
"/v1/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",
"format": "uuid",
"description": "Return only earnings attributed to this fan experience. Matches every charge the experience produced, including one-off access purchases, the first subscription charge and each renewal, plus the refunds and chargebacks that reverse any of them, so a filtered total nets out correctly. Combines with the other filters; normal pagination still applies.\n\nUse this rather than filtering on `source`: a renewal reports `source: \"renewal\"`, so `source=fanExperience` under-reports recurring experience revenue from the second charge onwards."
},
"required": false,
"description": "Return only earnings attributed to this fan experience. Matches every charge the experience produced, including one-off access purchases, the first subscription charge and each renewal, plus the refunds and chargebacks that reverse any of them, so a filtered total nets out correctly. Combines with the other filters; normal pagination still applies.\n\nUse this rather than filtering on `source`: a renewal reports `source: \"renewal\"`, so `source=fanExperience` under-reports recurring experience revenue from the second charge onwards.",
"name": "experienceUuid",
"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": "\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"
},
"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": "Pre-fee earnings for this row, converted to USD cents. Not always money a fan paid: `referral`, `affiliate` and `giveaway` rows are creator rewards. Negative on `refund` and `chargeback` rows, which carry the full amount of the earning they reverse, reward reversals included."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Negative on `refund` and `chargeback` rows."
},
"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"
},
"experienceUuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the fan experience this earning came from, present on every fan-experience charge: one-off access purchases, the first subscription charge, and each subsequent renewal. Same uuid an app receives as `experience.uuid` when a launch token is exchanged, so it joins directly to the app's own experience records.\n\nDetect experience revenue by this field's presence rather than by `source`: a renewal reports `source: \"renewal\"`, so filtering on `source: \"fanExperience\"` under-reports recurring experience revenue from the second charge onwards."
},
"experienceAppUuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the third-party app the `experienceUuid` experience belongs to. Present whenever `experienceUuid` is, and useful to separate experiences of different apps on the same creator."
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"thisMonth": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings this month, in USD cents, including earnings no fan paid for such as referrals. Excludes reversals."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees this month, in USD cents. Excludes reversals."
},
"previousMonthGross": {
"type": "number",
"description": "Same as `gross`, for the previous month, in USD cents"
},
"previousMonthNet": {
"type": "number",
"description": "Same as `net`, for the previous month, in USD cents"
},
"grossChangePercentage": {
"type": [
"number",
"null"
],
"description": "Change in `gross` against the previous month as a percentage. `null` when the previous month was zero and this month is not, and `0` when both months were zero."
},
"netChangePercentage": {
"type": [
"number",
"null"
],
"description": "Change in `net` against the previous month as a percentage. `null` when the previous month was zero and this month is not, and `0` when both months were zero."
}
},
"required": [
"gross",
"net",
"previousMonthGross",
"previousMonthNet",
"grossChangePercentage",
"netChangePercentage"
]
}
},
"required": [
"allTime",
"thisMonth"
]
},
"breakdownBySource": {
"type": "object",
"properties": {
"subs": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"messages": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"posts": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"tips": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"referrals": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"renewals": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"other": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
}
},
"required": [
"subs",
"messages",
"posts",
"tips",
"referrals",
"renewals",
"other"
]
},
"earningsByType": {
"type": "object",
"properties": {
"renewals": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"messages": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"tips": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"subs": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"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": "Pre-fee earnings in this bucket, in USD cents, including earnings no fan paid for such as referrals. Refunds and chargebacks are left out rather than subtracted."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees in this bucket, in USD cents. Refunds and chargebacks are left out rather than subtracted."
}
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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": "The reversed payment's amount, converted to USD cents. Every row here is a refund or chargeback, so this is negative and carries the full pre-fee amount of the earning it reverses. That is not always money a fan paid: a referral or affiliate earning can be clawed back too, and `user` is null on those rows."
},
"net": {
"type": "number",
"description": "Creator's reversal (refund/chargeback) impact after Fanvue fees, in USD cents. Negative for the same reason as `gross`."
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/insights/top-spenders": {
"get": {
"summary": "Get top-spending fans for a creator (cursor-paginated)",
"description": "Returns a cursor-paginated list of the top-spending fans for the specified creator with their spending totals and message counts.\n\nCursor-paginated: page with the opaque `nextCursor` from the previous response. The list is ordered by total spend descending, with a stable tiebreak so pages don't overlap or skip when fans have equal totals.\n\nTotals are summed over the requested date range, so the range is part of the ordering. The cursor carries it: when `cursor` is supplied, `startDate` and `endDate` are ignored and the walk continues over the range the first page used. Change the range by starting a new walk without a cursor.\n\n**Totals are a snapshot taken when the walk started.** Because the sort key is a recomputed sum, the whole walk has to aggregate one fixed set of payments or fans would move between pages and be missed. The first page fixes that set, and every later page reuses it, so the figures you page through stay mutually consistent — but a payment that lands mid-walk is not counted anywhere in it. Start a new walk without a cursor to pick up payments made since. In rare cases a fan can appear on two pages; de-duplicate on the fan `uuid`.",
"operationId": "getCreatorTopSpendersV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"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 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"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:insights",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated list of top-spending fans",
"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. Gross of reversals: only positive invoices are counted, so a refunded or charged-back purchase is left in at its full amount rather than subtracted. App Store purchases are counted here as well. Both differ from `spending.total` on /insights/fans/{userUuid}, which is net of reversals and leaves App Store purchases out because they record a creator buying an app from its developer."
},
"net": {
"type": "number",
"description": "Creator's total cut from this fan after Fanvue fees, in USD cents. Same reversal treatment as `gross`: fees are the only thing taken off."
},
"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": "Top-spending fans, highest total spend first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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"
}
}
],
"nextCursor": null,
"total": null
}
}
}
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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": "When this fan last paid this creator (ISO 8601), or null if they never have. Fan-initiated payments only, so an automatic subscription renewal never moves it, and App Store purchases do not count as a purchase here. Reversed purchases are NOT skipped: a purchase later refunded or charged back still counts as the last purchase, because the fan did reach for their wallet at that moment, which makes this recency of intent rather than recency of valid spend. Use `lastValidPurchaseAt` for the latter."
},
"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`, and net of reversals despite the field name."
},
"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. Net of reversals: a refund or chargeback is a separate invoice for the full original amount and is subtracted here, so this is normally lower than the sum of the gross `sources` figures and can be negative. Reversals are selected by their own type rather than by what they reverse, so a clawed-back creator reward the fan never paid for is subtracted here too, and this can fall below what the fan actually paid. It is not the same as `netTotal`, which is aggregated over the surviving purchases instead; the two differ for a purchase reversed without a reversal invoice, which has no negative row for this figure to subtract."
},
"netTotal": {
"type": "number",
"description": "Total this fan paid with refunded and charged-back purchases removed, in USD cents. Aggregated over the surviving purchases themselves, so it and the per-source `netTotal` values describe one set of purchases and add up. It usually equals `total`, which subtracts reversals by counting their negative rows; the two part company only for a reversal recorded on the original purchase without a row of its own, which `total` cannot see."
}
},
"required": [
"gross",
"total",
"netTotal"
]
},
"maxSinglePayment": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`, and excludes reversed purchases."
},
"total": {
"type": "number",
"description": "Largest single payment this fan made, in USD cents. Excludes App Store purchases, as `total` does. Excludes reversed purchases: a payment later refunded or charged back is not eligible, so this can be lower than the largest amount the fan ever paid. Reversal invoices themselves are never counted. This has been the behaviour since July 2025. A refund or chargeback marker on the payment counts as a reversal in its own right when no reversal invoice is linked, so a purchase reversed that way is excluded too; a purchase whose reversal was created and then failed stays eligible, because that reversal never settled."
}
},
"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`, and gross of reversals."
},
"total": {
"type": "number",
"description": "Total amount paid by the fan for this source type, in USD cents. Gross of reversals: a purchase that was later refunded or charged back is still counted here in full. Use `netTotal` for the figure with those purchases removed."
},
"netTotal": {
"type": "number",
"description": "Total paid from this source with refunded and charged-back purchases removed, in USD cents: the sum of the purchases that still stand, and the numerator of `netAverage`. Net of reversals only, not of Fanvue fees, unlike the `net` returned by /insights/earnings and /agencies/insights/*."
},
"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",
"netTotal",
"count",
"netCount",
"average",
"netAverage"
]
},
"description": "Breakdown of this fan's spend by source, keyed by the same source names /insights/earnings uses (so `renewal` is a catch-all for every recurring charge after the first payment). `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. Refunds and chargebacks are never a source entry of their own. Each entry carries both treatments: `total`, `count` and `average` are gross of reversals, so the `total` values do not sum to `total.total` and the difference is exactly the reversals, while `netTotal`, `netCount` and `netAverage` drop the reversed purchases and the `netTotal` values do sum to `total.netTotal`."
}
},
"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": 25700,
"total": 25700,
"netTotal": 25700
},
"maxSinglePayment": {
"gross": 5000,
"total": 5000
},
"sources": {
"message": {
"gross": 15000,
"total": 15000,
"netTotal": 13000,
"count": 6,
"netCount": 5,
"average": 2500,
"netAverage": 2600
},
"post": {
"gross": 8500,
"total": 8500,
"netTotal": 8500,
"count": 5,
"netCount": 5,
"average": 1700,
"netAverage": 1700
},
"referral": {
"gross": 4200,
"total": 4200,
"netTotal": 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"
}
}
}
},
"/v1/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\nMaximum 20 fan UUIDs per request.",
"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": "\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"
},
"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": "When this fan last paid this creator (ISO 8601), or null if they never have. Fan-initiated payments only, so an automatic subscription renewal never moves it, and App Store purchases do not count as a purchase here. Reversed purchases are NOT skipped: a purchase later refunded or charged back still counts as the last purchase, because the fan did reach for their wallet at that moment, which makes this recency of intent rather than recency of valid spend. Use `lastValidPurchaseAt` for the latter."
},
"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`, and net of reversals despite the field name."
},
"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. Net of reversals: a refund or chargeback is a separate invoice for the full original amount and is subtracted here, so this is normally lower than the sum of the gross `sources` figures and can be negative. Reversals are selected by their own type rather than by what they reverse, so a clawed-back creator reward the fan never paid for is subtracted here too, and this can fall below what the fan actually paid. It is not the same as `netTotal`, which is aggregated over the surviving purchases instead; the two differ for a purchase reversed without a reversal invoice, which has no negative row for this figure to subtract."
},
"netTotal": {
"type": "number",
"description": "Total this fan paid with refunded and charged-back purchases removed, in USD cents. Aggregated over the surviving purchases themselves, so it and the per-source `netTotal` values describe one set of purchases and add up. It usually equals `total`, which subtracts reversals by counting their negative rows; the two part company only for a reversal recorded on the original purchase without a row of its own, which `total` cannot see."
}
},
"required": [
"gross",
"total",
"netTotal"
]
},
"maxSinglePayment": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`, and excludes reversed purchases."
},
"total": {
"type": "number",
"description": "Largest single payment this fan made, in USD cents. Excludes App Store purchases, as `total` does. Excludes reversed purchases: a payment later refunded or charged back is not eligible, so this can be lower than the largest amount the fan ever paid. Reversal invoices themselves are never counted. This has been the behaviour since July 2025. A refund or chargeback marker on the payment counts as a reversal in its own right when no reversal invoice is linked, so a purchase reversed that way is excluded too; a purchase whose reversal was created and then failed stays eligible, because that reversal never settled."
}
},
"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`, and gross of reversals."
},
"total": {
"type": "number",
"description": "Total amount paid by the fan for this source type, in USD cents. Gross of reversals: a purchase that was later refunded or charged back is still counted here in full. Use `netTotal` for the figure with those purchases removed."
},
"netTotal": {
"type": "number",
"description": "Total paid from this source with refunded and charged-back purchases removed, in USD cents: the sum of the purchases that still stand, and the numerator of `netAverage`. Net of reversals only, not of Fanvue fees, unlike the `net` returned by /insights/earnings and /agencies/insights/*."
},
"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",
"netTotal",
"count",
"netCount",
"average",
"netAverage"
]
},
"description": "Breakdown of this fan's spend by source, keyed by the same source names /insights/earnings uses (so `renewal` is a catch-all for every recurring charge after the first payment). `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. Refunds and chargebacks are never a source entry of their own. Each entry carries both treatments: `total`, `count` and `average` are gross of reversals, so the `total` values do not sum to `total.total` and the difference is exactly the reversals, while `netTotal`, `netCount` and `netAverage` drop the reversed purchases and the `netTotal` values do sum to `total.netTotal`."
}
},
"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": 25700,
"total": 25700,
"netTotal": 25700
},
"maxSinglePayment": {
"gross": 5000,
"total": 5000
},
"sources": {
"message": {
"gross": 15000,
"total": 15000,
"netTotal": 13000,
"count": 6,
"netCount": 5,
"average": 2500,
"netAverage": 2600
},
"post": {
"gross": 8500,
"total": 8500,
"netTotal": 8500,
"count": 5,
"netCount": 5,
"average": 1700,
"netAverage": 1700
},
"referral": {
"gross": 4200,
"total": 4200,
"netTotal": 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"
}
}
}
},
"/v1/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\nMaximum 100 fan UUIDs per request. Failed keys are reported as `{ \"error\": \"forbidden\" | \"not_found\" | \"internal\" }`.",
"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": "\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"
},
"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": "When this fan last paid this creator (ISO 8601), or null if they never have. Fan-initiated payments only, so an automatic subscription renewal never moves it, and App Store purchases do not count as a purchase here. Reversed purchases are NOT skipped: a purchase later refunded or charged back still counts as the last purchase, because the fan did reach for their wallet at that moment, which makes this recency of intent rather than recency of valid spend. Use `lastValidPurchaseAt` for the latter."
},
"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`, and net of reversals despite the field name."
},
"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. Net of reversals: a refund or chargeback is a separate invoice for the full original amount and is subtracted here, so this is normally lower than the sum of the gross `sources` figures and can be negative. Reversals are selected by their own type rather than by what they reverse, so a clawed-back creator reward the fan never paid for is subtracted here too, and this can fall below what the fan actually paid. It is not the same as `netTotal`, which is aggregated over the surviving purchases instead; the two differ for a purchase reversed without a reversal invoice, which has no negative row for this figure to subtract."
},
"netTotal": {
"type": "number",
"description": "Total this fan paid with refunded and charged-back purchases removed, in USD cents. Aggregated over the surviving purchases themselves, so it and the per-source `netTotal` values describe one set of purchases and add up. It usually equals `total`, which subtracts reversals by counting their negative rows; the two part company only for a reversal recorded on the original purchase without a row of its own, which `total` cannot see."
}
},
"required": [
"gross",
"total",
"netTotal"
]
},
"maxSinglePayment": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`, and excludes reversed purchases."
},
"total": {
"type": "number",
"description": "Largest single payment this fan made, in USD cents. Excludes App Store purchases, as `total` does. Excludes reversed purchases: a payment later refunded or charged back is not eligible, so this can be lower than the largest amount the fan ever paid. Reversal invoices themselves are never counted. This has been the behaviour since July 2025. A refund or chargeback marker on the payment counts as a reversal in its own right when no reversal invoice is linked, so a purchase reversed that way is excluded too; a purchase whose reversal was created and then failed stays eligible, because that reversal never settled."
}
},
"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`, and gross of reversals."
},
"total": {
"type": "number",
"description": "Total amount paid by the fan for this source type, in USD cents. Gross of reversals: a purchase that was later refunded or charged back is still counted here in full. Use `netTotal` for the figure with those purchases removed."
},
"netTotal": {
"type": "number",
"description": "Total paid from this source with refunded and charged-back purchases removed, in USD cents: the sum of the purchases that still stand, and the numerator of `netAverage`. Net of reversals only, not of Fanvue fees, unlike the `net` returned by /insights/earnings and /agencies/insights/*."
},
"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",
"netTotal",
"count",
"netCount",
"average",
"netAverage"
]
},
"description": "Breakdown of this fan's spend by source, keyed by the same source names /insights/earnings uses (so `renewal` is a catch-all for every recurring charge after the first payment). `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. Refunds and chargebacks are never a source entry of their own. Each entry carries both treatments: `total`, `count` and `average` are gross of reversals, so the `total` values do not sum to `total.total` and the difference is exactly the reversals, while `netTotal`, `netCount` and `netAverage` drop the reversed purchases and the `netTotal` values do sum to `total.netTotal`."
}
},
"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": 7000,
"total": 7000,
"netTotal": 7000
},
"maxSinglePayment": {
"gross": 5000,
"total": 5000
},
"sources": {
"subscription": {
"gross": 7000,
"total": 7000,
"netTotal": 7000,
"count": 7,
"netCount": 7,
"average": 1000,
"netAverage": 1000
},
"tips": {
"gross": 5000,
"total": 5000,
"netTotal": 0,
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/posts": {
"get": {
"summary": "Get posts for a creator (cursor-paginated)",
"description": "Returns a cursor-paginated list of posts created by the specified creator, ordered by pinned status first, then by publication date (newest first). Keyset pagination is stable under concurrent writes and has constant per-page cost, unlike the offset-paginated v0 endpoint. Page with the opaque `nextCursor`.",
"operationId": "getCreatorPostsV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`. It carries the includeUnpublished flag and date range the first page was cut under, so later pages need nothing but the cursor. Resending those filters is allowed while they match it; a value that contradicts the cursor is rejected."
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`. It carries the includeUnpublished flag and date range the first page was cut under, so later pages need nothing but the cursor. Resending those filters is allowed while they match it; a value that contradicts the cursor is rejected.",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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",
"enum": [
"true",
"false"
],
"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": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, pinned first then most recently published"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"example": {
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2025-01-16T14:20:00.000Z",
"text": "Behind the scenes from today's shoot",
"price": null,
"mediaPreviewUuid": null,
"audience": "subscribers",
"publishAt": null,
"publishedAt": "2025-01-16T14:20:00.000Z",
"expiresAt": null,
"mediaUuids": [
"550e8400-e29b-41d4-a716-446655440010"
],
"isPinned": true,
"likesCount": 42,
"commentsCount": 5,
"tips": {
"count": 3,
"totalGross": 1500,
"totalNet": 1275
},
"collections": []
}
],
"nextCursor": "k0FQ1m9yb3ZpZGVkQnlUaGVBUEk",
"total": 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"
}
}
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/posts/{uuid}/tips": {
"get": {
"summary": "Get tips for a creator's post (cursor-paginated)",
"description": "Cursor-paginated list of tips received on a specific post owned by the specified creator, most recent first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent tips, unlike the offset-paginated v0 endpoint.",
"operationId": "getCreatorPostTipsV1",
"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": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:post",
"read:creator"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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-15T00:00:00.000Z",
"gross": 2000,
"net": 1700
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": "Post not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"410": {
"$ref": "#/components/responses/SunsetVersionResponse"
},
"429": {
"$ref": "#/components/responses/RateLimitResponse"
}
}
}
},
"/v1/creators/{creatorUserUuid}/posts/{uuid}/likes": {
"get": {
"summary": "Get likes for a creator's post (cursor-paginated)",
"description": "Cursor-paginated list of likes on a specific post owned by the specified creator, most recent first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent likes, unlike the offset-paginated v0 endpoint.",
"operationId": "getCreatorPostLikesV1",
"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": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:post",
"read:creator"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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-15T00:00:00.000Z"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": "Post not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"410": {
"$ref": "#/components/responses/SunsetVersionResponse"
},
"429": {
"$ref": "#/components/responses/RateLimitResponse"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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 for a creator's post (cursor-paginated)",
"description": "Cursor-paginated list of comments on a specific post owned by the specified creator, most recent first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent comments, unlike the offset-paginated v0 endpoint.",
"operationId": "getCreatorPostCommentsV1",
"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": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:post",
"read:creator"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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-15T00:00:00.000Z",
"updatedAt": null
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": "Post not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"410": {
"$ref": "#/components/responses/SunsetVersionResponse"
},
"429": {
"$ref": "#/components/responses/RateLimitResponse"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/chats/lists/smart/{uuid}": {
"get": {
"summary": "Get creator's smart list members (cursor-paginated)",
"description": "Get members of a specific smart list for a creator. Smart lists are system-generated dynamic audience segments (not user-created lists). The returned members are filtered by contactability and the selected smart list type.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to an opaque `cursor`. Page with the `nextCursor` from the previous response and keep `size` constant for the whole walk. `total` is not computed for this list and is always `null`.",
"operationId": "getCreatorSmartListMembersV1",
"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": "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"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:chat",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"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": [
{
"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
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/chats/lists/custom": {
"get": {
"summary": "Get creator's custom lists (cursor-paginated)",
"description": "Get a creator's custom lists with member counts.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to an opaque `cursor`. Page with the `nextCursor` from the previous response and keep `size` constant for the whole walk. `total` is not computed for this list and is always `null`.",
"operationId": "getCreatorCustomListsV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"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",
"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:creator",
"read:chat",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"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": [
{
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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"
}
}
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/chats/lists/custom/{uuid}": {
"get": {
"summary": "Get creator's custom list members (cursor-paginated)",
"description": "Get members of a specific custom list for a creator, most recently added first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable while members are added or removed, unlike the offset-paginated v0 endpoint.",
"operationId": "getCreatorCustomListMembersV1",
"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",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:chat",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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": "Array of list members, most recently added first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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"
}
}
},
"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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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\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",
"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",
"pattern": "^\\d+$",
"description": "Cursor for pagination, as returned in a previous page's `nextCursor`."
},
"required": false,
"description": "Cursor for pagination, as returned in a previous page's `nextCursor`.",
"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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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": "Informational only — the local currency the fan originally paid in (e.g. 'BRL'). The gross, net, and fee amounts are already converted to USD minor units regardless of this value."
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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": "Informational only — the local currency the fan originally paid in (e.g. 'BRL'). The gross, net, and fee amounts are already converted to USD minor units regardless of this value."
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/checkout-links/subscriptions": {
"get": {
"summary": "List a creator's checkout-link subscriptions",
"description": "List the specified creator's checkout-link product subscriptions, most recent first, with cursor-based pagination. Defaults to `status=active` (renewing); pass `status=cancelled` for active subscriptions scheduled to cancel at the period end (`cancelAtPeriodEnd=true` — their resource `status` stays `active` until they expire), `status=expired` for ended ones, or `status=all`. Filter by `checkoutLinkUuid` or `fanUuid` to narrow the list.\n\n\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.subscription.activated`, `checkout_link.subscription.deactivated`, `checkout_link.subscription.cancel_at_period_end_changed` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/checkout/subscriptions).\n",
"operationId": "listCreatorCheckoutLinkSubscriptions",
"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",
"pattern": "^\\d+$",
"description": "Cursor for pagination, as returned in a previous page's `nextCursor`."
},
"required": false,
"description": "Cursor for pagination, as returned in a previous page's `nextCursor`.",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"active",
"cancelled",
"expired",
"all"
],
"description": "Filter (default `active`). `active` returns renewing subscriptions; `cancelled` returns active subscriptions scheduled to cancel at the period end (`cancelAtPeriodEnd=true` — their resource `status` is still `active`); `expired` returns ended subscriptions."
},
"required": false,
"description": "Filter (default `active`). `active` returns renewing subscriptions; `cancelled` returns active subscriptions scheduled to cancel at the period end (`cancelAtPeriodEnd=true` — their resource `status` is still `active`); `expired` returns ended subscriptions.",
"name": "status",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid",
"description": "Filter to subscriptions purchased through this checkout link."
},
"required": false,
"description": "Filter to subscriptions purchased through this checkout link.",
"name": "checkoutLinkUuid",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uuid",
"description": "Filter to subscriptions held by this fan."
},
"required": false,
"description": "Filter to subscriptions held by this fan.",
"name": "fanUuid",
"in": "query"
}
],
"security": [
{
"BearerAuth": [
"read:creator"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"responses": {
"200": {
"description": "List of checkout-link subscriptions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Fanvue's unique subscription identifier."
},
"status": {
"type": "string",
"enum": [
"active",
"expired"
],
"description": "Access state of the subscription, matching the `checkout_link.subscription.*` webhooks: `active` means the fan currently has access (including subscriptions scheduled to cancel at the period end — check `cancelAtPeriodEnd`), `expired` means access has ended. Revoke access only on `expired`."
},
"cancelAtPeriodEnd": {
"type": "boolean",
"description": "True when the subscription is set to end (not renew) at `expiresAt`."
},
"cancelledBy": {
"type": [
"string",
"null"
],
"enum": [
"fan",
"creator",
"admin"
],
"description": "Who initiated a pending cancellation: the subscriber themselves (`fan`), the creator (dashboard or this API), or Fanvue support (`admin`). Null when the subscription is not cancelled, or for older cancellations made before the actor was recorded. Only `creator` cancellations can be reversed via the uncancel endpoint."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "End of the current paid period: the next renewal date, or when access ends."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the subscription started."
},
"clientReferenceId": {
"type": [
"string",
"null"
],
"description": "The merchant-supplied reference passed at checkout via `?client_reference_id=`, inherited from the initial payment."
},
"checkoutLink": {
"type": [
"object",
"null"
],
"properties": {
"uuid": {
"type": "string",
"description": "UUID of the checkout link the fan converted on."
},
"name": {
"type": "string",
"description": "Name of the checkout link / offer."
}
},
"required": [
"uuid",
"name"
],
"description": "The checkout link the subscription was purchased through, if known."
},
"purchaser": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "UUID of the subscribing Fanvue user."
},
"email": {
"type": [
"string",
"null"
],
"description": "Email of the subscribing Fanvue user."
}
},
"required": [
"uuid",
"email"
]
},
"price": {
"type": [
"object",
"null"
],
"properties": {
"amount": {
"type": "number",
"description": "Recurring price, in minor units."
},
"currency": {
"type": "string",
"description": "ISO currency code of the amount."
},
"cycleLength": {
"type": [
"number",
"null"
],
"description": "Length of the billing cycle, in `cycleUnit`s."
},
"cycleUnit": {
"type": [
"string",
"null"
],
"enum": [
"day",
"week",
"month",
"year"
],
"description": "Unit of the billing cycle, matching the checkout-link price schema."
}
},
"required": [
"amount",
"currency",
"cycleLength",
"cycleUnit"
],
"description": "The recurring price the subscription renews at."
},
"metadata": {
"type": "object",
"additionalProperties": {},
"description": "Arbitrary merchant metadata passed at checkout via `?metadata[key]=value`, inherited from the initial payment."
}
},
"required": [
"uuid",
"status",
"cancelAtPeriodEnd",
"cancelledBy",
"expiresAt",
"createdAt",
"clientReferenceId",
"checkoutLink",
"purchaser",
"price",
"metadata"
]
}
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null if none."
}
},
"required": [
"data",
"nextCursor"
]
},
"example": {
"data": [
{
"uuid": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
"status": "active",
"cancelAtPeriodEnd": false,
"cancelledBy": null,
"expiresAt": "2026-07-19T08:30:00.000Z",
"createdAt": "2026-06-19T08:30:00.000Z",
"clientReferenceId": "order_9f8c",
"checkoutLink": {
"uuid": "0b3c0e4a-1f2d-4c8a-9a1b-3e5f7a9c1d2e",
"name": "Premium Coaching"
},
"purchaser": {
"uuid": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
"email": "buyer@example.com"
},
"price": {
"amount": 1999,
"currency": "USD",
"cycleLength": 1,
"cycleUnit": "month"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/checkout-links/subscriptions/{uuid}/cancel": {
"post": {
"summary": "Cancel a creator's checkout-link subscription at the period end",
"description": "Stop the specified subscription from renewing. The fan keeps access until `expiresAt` — the response's `status` stays `active` with `cancelAtPeriodEnd: true` — and the subscription then ends without a further charge. Emits the `checkout_link.subscription.cancel_at_period_end_changed` webhook. Returns 400 if the subscription is already set to cancel, and 404 if it does not exist, has ended, or does not belong to this creator.\n\nCancelling a subscription in payment retry — a failed renewal Fanvue is still reattempting — stops further charge attempts immediately. The response then reflects the already-ended access (`status: expired`), and no webhook is emitted: the `checkout_link.subscription.deactivated` event already fired when the failed renewal ended the subscription.",
"operationId": "cancelCreatorCheckoutLinkSubscription",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid",
"description": "Fanvue subscription identifier."
},
"required": true,
"description": "Fanvue subscription identifier.",
"name": "uuid",
"in": "path"
}
],
"security": [
{
"BearerAuth": [
"write:creator"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"responses": {
"200": {
"description": "Subscription set to cancel at the period end",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Fanvue's unique subscription identifier."
},
"status": {
"type": "string",
"enum": [
"active",
"expired"
],
"description": "Access state of the subscription, matching the `checkout_link.subscription.*` webhooks: `active` means the fan currently has access (including subscriptions scheduled to cancel at the period end — check `cancelAtPeriodEnd`), `expired` means access has ended. Revoke access only on `expired`."
},
"cancelAtPeriodEnd": {
"type": "boolean",
"description": "True when the subscription is set to end (not renew) at its period end."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "End of the current paid period: when access ends, or the next renewal date."
}
},
"required": [
"uuid",
"status",
"cancelAtPeriodEnd",
"expiresAt"
]
},
"example": {
"uuid": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
"status": "active",
"cancelAtPeriodEnd": true,
"expiresAt": "2026-07-19T08:30: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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/checkout-links/subscriptions/{uuid}/uncancel": {
"post": {
"summary": "Reactivate a cancelled checkout-link subscription",
"description": "Reverse a pending cancel-at-period-end while the paid period is still running, so the subscription renews again at `expiresAt`. Emits the `checkout_link.subscription.cancel_at_period_end_changed` webhook with `cancel_at_period_end: false`. Returns 400 if the subscription is not set to cancel or has already ended (an ended subscription cannot be revived), and 404 if it does not exist or does not belong to this creator.\n\nOnly cancellations the creator made themselves (`cancelledBy: creator`) can be reversed here. If the subscriber cancelled — or Fanvue support did, or the cancellation is older than actor tracking and carries `cancelledBy: null` — the endpoint returns 409 and the cancellation stands: only the subscriber can restart their own subscription, by purchasing again.",
"operationId": "uncancelCreatorCheckoutLinkSubscription",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid",
"description": "Fanvue subscription identifier."
},
"required": true,
"description": "Fanvue subscription identifier.",
"name": "uuid",
"in": "path"
}
],
"security": [
{
"BearerAuth": [
"write:creator"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"responses": {
"200": {
"description": "Subscription renewing again",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Fanvue's unique subscription identifier."
},
"status": {
"type": "string",
"enum": [
"active",
"expired"
],
"description": "Access state of the subscription, matching the `checkout_link.subscription.*` webhooks: `active` means the fan currently has access (including subscriptions scheduled to cancel at the period end — check `cancelAtPeriodEnd`), `expired` means access has ended. Revoke access only on `expired`."
},
"cancelAtPeriodEnd": {
"type": "boolean",
"description": "True when the subscription is set to end (not renew) at its period end."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "End of the current paid period: when access ends, or the next renewal date."
}
},
"required": [
"uuid",
"status",
"cancelAtPeriodEnd",
"expiresAt"
]
},
"example": {
"uuid": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
"status": "active",
"cancelAtPeriodEnd": false,
"expiresAt": "2026-07-19T08:30: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"
},
"409": {
"description": "The cancellation was made by the subscriber (or Fanvue support), or predates actor tracking, so the creator cannot reverse it",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"410": {
"$ref": "#/components/responses/SunsetVersionResponse"
},
"429": {
"$ref": "#/components/responses/RateLimitResponse"
}
}
}
},
"/v1/creators/{creatorUserUuid}/checkout-links": {
"get": {
"summary": "List a creator's checkout links (cursor-paginated)",
"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).\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent writes, unlike the offset-paginated v0 endpoint.",
"operationId": "listCreatorCheckoutLinksV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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//`. 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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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//fv-3?campaign=spring_launch`), using plain query parameters rather than the `metadata[]` 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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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\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",
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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 (cursor-paginated)",
"description": "Returns a cursor-paginated list of folders in the specified creator's vault, oldest first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination, and dropped the per-folder `mediaCount` — computing it was a second query keyset pagination avoids. Page with the opaque `nextCursor`.",
"operationId": "listCreatorVaultFoldersV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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",
"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:creator",
"read:media"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
}
},
"required": [
"name",
"createdAt"
]
},
"description": "Array of vault folders, oldest first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"example": {
"data": [
{
"name": "Behind the scenes",
"createdAt": "2024-01-13T00:00:00.000Z"
},
{
"name": "Premium sets",
"createdAt": "2024-01-15T00:00:00.000Z"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/vault/folders/{folderName}/media": {
"get": {
"summary": "List media in creator vault folder (cursor-paginated)",
"description": "Returns a cursor-paginated list of media items in the specified creator folder.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`, which pins the sort, order and membership filters for the whole walk — a continuation request only needs to echo `cursor` (and may vary `size` and `variants`).",
"operationId": "listCreatorVaultFolderMediaV1",
"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",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"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",
"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:creator",
"read:media"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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 in the folder"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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"
}
],
"nextCursor": null,
"total": 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"
}
}
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/account-health/flagged-media": {
"get": {
"summary": "List a creator's flagged media (cursor-paginated)",
"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.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to an opaque `cursor`. Page with the `nextCursor` from the previous response and keep `size` constant for the whole walk. `total` is not computed for this list and is always `null`.",
"operationId": "listCreatorFlaggedMediaV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"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",
"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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"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": [
{
"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"
}
],
"nextCursor": null,
"total": 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"
}
}
}
},
"/v1/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": "\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"
},
"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": "\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"
},
"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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/blocks": {
"get": {
"summary": "List users blocked by a creator (cursor-paginated)",
"description": "List the users the specified creator has blocked, newest blocked account first (the same ordering as the v0 endpoint; it does not reflect when each block was applied), with keyset pagination. Keyset pagination is stable under concurrent writes and has constant per-page cost, unlike the offset-paginated v0 endpoint. Page with the opaque `nextCursor`.",
"operationId": "listCreatorBlockedUsersV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:chat",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"example": {
"data": [
{
"uuid": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"handle": "blockeduser",
"displayName": "Blocked User",
"avatarUrl": "https://cdn.fanvue.com/avatars/b3f1c2d4.jpg"
}
],
"nextCursor": null,
"total": 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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/chats/templates": {
"get": {
"summary": "Get a creator's template messages (cursor-paginated)",
"description": "Returns a cursor-paginated list of the specified creator's template messages. Optionally filter by folder name using case-insensitive partial matching. Page with the opaque `nextCursor` from the previous response and keep `size` constant for the whole walk. `total` is not computed for this list and is always `null`.",
"operationId": "listCreatorTemplateMessages",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"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",
"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:creator",
"read:chat"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"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": [
{
"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
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I",
"total": 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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/chats/templates/folders": {
"get": {
"summary": "Get a creator's template folders (cursor-paginated)",
"description": "Returns a cursor-paginated list of the specified creator's template folders. Use a folder name to narrow GET /creators/{creatorUserUuid}/chats/templates. Page with the opaque `nextCursor` from the previous response and keep `size` constant for the whole walk. `total` is not computed for this list and is always `null`.",
"operationId": "listCreatorTemplateFolders",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:chat"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"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": [
{
"uuid": "b0a1c2d3-e4f5-6789-abcd-ef0123456789",
"name": "Welcome Messages"
},
{
"uuid": "c1b2a3d4-f5e6-7890-bcde-f01234567890",
"name": "Promotions"
}
],
"nextCursor": null,
"total": 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"
}
}
}
},
"/v1/creators/{creatorUserUuid}/chats/templates/{templateUuid}": {
"get": {
"summary": "Get one of a creator's template messages",
"description": "Returns a single template message belonging to the specified creator.",
"operationId": "getCreatorTemplateMessage",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"required": true,
"name": "creatorUserUuid",
"in": "path"
},
{
"schema": {
"type": "string",
"format": "uuid",
"description": "Template message UUID"
},
"required": true,
"description": "Template message UUID",
"name": "templateUuid",
"in": "path"
}
],
"security": [
{
"BearerAuth": [
"read:creator",
"read:chat"
]
}
],
"x-mint": {
"content": "\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"
},
"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"
}
}
}
},
"/v1/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": "\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"
},
"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"
}
}
}
}
}
}
}
}
},
"/v1/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.\n\n A publish request may narrow the access modes the creator is offered with `allowedAccessModes`; an incoherent constraint (empty, duplicated, or not containing `proposedAccessMode`) is rejected with 400 and a message naming the rule it broke.",
"operationId": "mintExperienceRequestToken",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"write:experience"
]
}
],
"x-mint": {
"content": "\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"
},
"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"
]
},
"allowedAccessModes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"FREE",
"SUBSCRIPTION",
"PAID",
"HIDDEN"
]
},
"minItems": 1,
"maxItems": 4,
"description": "Restricts which access modes the creator may choose in the Fanvue confirmation modal. Must contain `proposedAccessMode` and hold no duplicates. Omit to offer all four modes.",
"example": [
"FREE"
]
},
"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 OR the requested allowedAccessModes constraint was rejected",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/UnsupportedVersionError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": false
}
]
}
}
}
},
"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"
}
}
}
}
}
}
}
}
},
"/v1/followers": {
"get": {
"summary": "Get followers (cursor-paginated)",
"description": "Returns the users who follow the authenticated user, most recently followed first.\n\nA fan who both follows and holds an active subscription appears in this list as well as in the subscribers list, so the two are not disjoint — de-duplicate on the user `uuid` if you merge them.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent follows, unlike the offset-paginated v0 endpoint.\n\n\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",
"operationId": "listFollowers_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:fan"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:fan` — Access fan-related data and information within the platform.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recently followed first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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\nPass `experienceUuid` to return only the revenue one fan experience produced: its one-off access purchases, its first subscription charge, every renewal, and the refunds and chargebacks reversing any of them. Every row also reports `experienceUuid` and `experienceAppUuid`, so an unfiltered page can be attributed client-side too.\n\n\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\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",
"format": "uuid",
"description": "Return only earnings attributed to this fan experience. Matches every charge the experience produced, including one-off access purchases, the first subscription charge and each renewal, plus the refunds and chargebacks that reverse any of them, so a filtered total nets out correctly. Combines with the other filters; normal pagination still applies.\n\nUse this rather than filtering on `source`: a renewal reports `source: \"renewal\"`, so `source=fanExperience` under-reports recurring experience revenue from the second charge onwards."
},
"required": false,
"description": "Return only earnings attributed to this fan experience. Matches every charge the experience produced, including one-off access purchases, the first subscription charge and each renewal, plus the refunds and chargebacks that reverse any of them, so a filtered total nets out correctly. Combines with the other filters; normal pagination still applies.\n\nUse this rather than filtering on `source`: a renewal reports `source: \"renewal\"`, so `source=fanExperience` under-reports recurring experience revenue from the second charge onwards.",
"name": "experienceUuid",
"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": "\n **Required scope**\n\n - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n"
},
"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": "Pre-fee earnings for this row, converted to USD cents. Not always money a fan paid: `referral`, `affiliate` and `giveaway` rows are creator rewards. Negative on `refund` and `chargeback` rows, which carry the full amount of the earning they reverse, reward reversals included."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Negative on `refund` and `chargeback` rows."
},
"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"
},
"experienceUuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the fan experience this earning came from, present on every fan-experience charge: one-off access purchases, the first subscription charge, and each subsequent renewal. Same uuid an app receives as `experience.uuid` when a launch token is exchanged, so it joins directly to the app's own experience records.\n\nDetect experience revenue by this field's presence rather than by `source`: a renewal reports `source: \"renewal\"`, so filtering on `source: \"fanExperience\"` under-reports recurring experience revenue from the second charge onwards."
},
"experienceAppUuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the third-party app the `experienceUuid` experience belongs to. Present whenever `experienceUuid` is, and useful to separate experiences of different apps on the same creator."
},
"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"
}
}
}
},
"/v1/insights/earnings/summary": {
"get": {
"summary": "Get aggregated earnings summary",
"description": "Returns pre-aggregated earnings metrics for the authenticated creator, including all-time totals, month-over-month comparisons, source/type breakdowns, chart series, and averages.\n\nAlmost every money field pairs `gross` (pre-fee earnings) with `net` (the creator's cut after Fanvue fees); refunds and chargebacks are left out of both rather than subtracted. The exception is `averageByDayOfWeek` and `averageByHourOfDay`: both are gross-only scalars with no net counterpart to select. `gross` is not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`.\n\nUnlike the fan insights endpoints, results here are cached for up to 10 minutes per creator and per parameter set, so a figure can lag a payment that has already settled.",
"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": "\n **Required scope**\n\n - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n"
},
"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": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"thisMonth": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings this month, in USD cents, including earnings no fan paid for such as referrals. Excludes reversals."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees this month, in USD cents. Excludes reversals."
},
"previousMonthGross": {
"type": "number",
"description": "Same as `gross`, for the previous month, in USD cents"
},
"previousMonthNet": {
"type": "number",
"description": "Same as `net`, for the previous month, in USD cents"
},
"grossChangePercentage": {
"type": [
"number",
"null"
],
"description": "Change in `gross` against the previous month as a percentage. `null` when the previous month was zero and this month is not, and `0` when both months were zero."
},
"netChangePercentage": {
"type": [
"number",
"null"
],
"description": "Change in `net` against the previous month as a percentage. `null` when the previous month was zero and this month is not, and `0` when both months were zero."
}
},
"required": [
"gross",
"net",
"previousMonthGross",
"previousMonthNet",
"grossChangePercentage",
"netChangePercentage"
]
}
},
"required": [
"allTime",
"thisMonth"
]
},
"breakdownBySource": {
"type": "object",
"properties": {
"subs": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"messages": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"posts": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"tips": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"referrals": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"renewals": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"other": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
}
},
"required": [
"subs",
"messages",
"posts",
"tips",
"referrals",
"renewals",
"other"
]
},
"earningsByType": {
"type": "object",
"properties": {
"renewals": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"messages": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"tips": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"required": [
"gross",
"net"
]
},
"subs": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "Pre-fee earnings, in USD cents. Not always money a fan paid: referral, affiliate and giveaway earnings are creator rewards that no fan paid for, and they reach this summary through `referrals` and `other`. Refunds and chargebacks are left out of this figure rather than subtracted from it."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees, in USD cents. Refunds and chargebacks are left out of this figure rather than subtracted from it."
}
},
"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": "Pre-fee earnings in this bucket, in USD cents, including earnings no fan paid for such as referrals. Refunds and chargebacks are left out rather than subtracted."
},
"net": {
"type": "number",
"description": "Creator's cut after Fanvue fees in this bucket, in USD cents. Refunds and chargebacks are left out rather than subtracted."
}
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n"
},
"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"
}
}
}
},
"/v1/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.\n\nA reversal is written as its own invoice rather than as a change to the payment it reverses, and always for the full original amount, because Fanvue has no partial refunds. The original payment therefore stays settled and keeps its own row on `/insights/earnings`; read `reversedTransactionOrderId` on the `refund`/`chargeback` rows there to pair the two.\n\nOne gap: a payment that already carries its refund or chargeback marker without a linked reversal invoice never gets one written, so a reversal recorded that way has no row here and nothing to pair.",
"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": "\n **Required scope**\n\n - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n"
},
"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": "The reversed payment's amount, converted to USD cents. Every row here is a refund or chargeback, so this is negative and carries the full pre-fee amount of the earning it reverses. That is not always money a fan paid: a referral or affiliate earning can be clawed back too, and `user` is null on those rows."
},
"net": {
"type": "number",
"description": "Creator's reversal (refund/chargeback) impact after Fanvue fees, in USD cents. Negative for the same reason as `gross`."
},
"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"
}
}
}
},
"/v1/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\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",
"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": "\n **Required scope**\n\n - `read:insights` — Access analytics, metrics, and insights data for performance tracking.\n"
},
"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"
}
}
}
},
"/v1/insights/top-spenders": {
"get": {
"summary": "Get top-spending fans (cursor-paginated)",
"description": "Returns a cursor-paginated list of the top-spending fans for the authenticated creator with their spending totals and message counts.\n\nCursor-paginated: page with the opaque `nextCursor` from the previous response. The list is ordered by total spend descending, with a stable tiebreak so pages don't overlap or skip when fans have equal totals.\n\nTotals are summed over the requested date range, so the range is part of the ordering. The cursor carries it: when `cursor` is supplied, `startDate` and `endDate` are ignored and the walk continues over the range the first page used. Change the range by starting a new walk without a cursor.\n\n**Totals are a snapshot taken when the walk started.** Because the sort key is a recomputed sum, the whole walk has to aggregate one fixed set of payments or fans would move between pages and be missed. The first page fixes that set, and every later page reuses it, so the figures you page through stay mutually consistent — but a payment that lands mid-walk is not counted anywhere in it. Start a new walk without a cursor to pick up payments made since. In rare cases a fan can appear on two pages; de-duplicate on the fan `uuid`.",
"operationId": "listTopSpendersV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"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 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"
}
],
"security": [
{
"BearerAuth": [
"read:insights",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"responses": {
"200": {
"description": "Cursor-paginated list of top-spending fans",
"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. Gross of reversals: only positive invoices are counted, so a refunded or charged-back purchase is left in at its full amount rather than subtracted. App Store purchases are counted here as well. Both differ from `spending.total` on /insights/fans/{userUuid}, which is net of reversals and leaves App Store purchases out because they record a creator buying an app from its developer."
},
"net": {
"type": "number",
"description": "Creator's total cut from this fan after Fanvue fees, in USD cents. Same reversal treatment as `gross`: fees are the only thing taken off."
},
"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": "Top-spending fans, highest total spend first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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"
}
}
],
"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"
}
}
}
},
"/v1/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\nEvery field carries the same meaning as on `GET /insights/fans/{userUuid}`, including which money fields are net of reversals and which are gross, and the same absence of caching.\n\nMaximum 20 fan UUIDs per request.",
"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": "\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"
},
"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": "When this fan last paid this creator (ISO 8601), or null if they never have. Fan-initiated payments only, so an automatic subscription renewal never moves it, and App Store purchases do not count as a purchase here. Reversed purchases are NOT skipped: a purchase later refunded or charged back still counts as the last purchase, because the fan did reach for their wallet at that moment, which makes this recency of intent rather than recency of valid spend. Use `lastValidPurchaseAt` for the latter."
},
"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`, and net of reversals despite the field name."
},
"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. Net of reversals: a refund or chargeback is a separate invoice for the full original amount and is subtracted here, so this is normally lower than the sum of the gross `sources` figures and can be negative. Reversals are selected by their own type rather than by what they reverse, so a clawed-back creator reward the fan never paid for is subtracted here too, and this can fall below what the fan actually paid. It is not the same as `netTotal`, which is aggregated over the surviving purchases instead; the two differ for a purchase reversed without a reversal invoice, which has no negative row for this figure to subtract."
},
"netTotal": {
"type": "number",
"description": "Total this fan paid with refunded and charged-back purchases removed, in USD cents. Aggregated over the surviving purchases themselves, so it and the per-source `netTotal` values describe one set of purchases and add up. It usually equals `total`, which subtracts reversals by counting their negative rows; the two part company only for a reversal recorded on the original purchase without a row of its own, which `total` cannot see."
}
},
"required": [
"gross",
"total",
"netTotal"
]
},
"maxSinglePayment": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`, and excludes reversed purchases."
},
"total": {
"type": "number",
"description": "Largest single payment this fan made, in USD cents. Excludes App Store purchases, as `total` does. Excludes reversed purchases: a payment later refunded or charged back is not eligible, so this can be lower than the largest amount the fan ever paid. Reversal invoices themselves are never counted. This has been the behaviour since July 2025. A refund or chargeback marker on the payment counts as a reversal in its own right when no reversal invoice is linked, so a purchase reversed that way is excluded too; a purchase whose reversal was created and then failed stays eligible, because that reversal never settled."
}
},
"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`, and gross of reversals."
},
"total": {
"type": "number",
"description": "Total amount paid by the fan for this source type, in USD cents. Gross of reversals: a purchase that was later refunded or charged back is still counted here in full. Use `netTotal` for the figure with those purchases removed."
},
"netTotal": {
"type": "number",
"description": "Total paid from this source with refunded and charged-back purchases removed, in USD cents: the sum of the purchases that still stand, and the numerator of `netAverage`. Net of reversals only, not of Fanvue fees, unlike the `net` returned by /insights/earnings and /agencies/insights/*."
},
"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",
"netTotal",
"count",
"netCount",
"average",
"netAverage"
]
},
"description": "Breakdown of this fan's spend by source, keyed by the same source names /insights/earnings uses (so `renewal` is a catch-all for every recurring charge after the first payment). `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. Refunds and chargebacks are never a source entry of their own. Each entry carries both treatments: `total`, `count` and `average` are gross of reversals, so the `total` values do not sum to `total.total` and the difference is exactly the reversals, while `netTotal`, `netCount` and `netAverage` drop the reversed purchases and the `netTotal` values do sum to `total.netTotal`."
}
},
"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": 25700,
"total": 25700,
"netTotal": 25700
},
"maxSinglePayment": {
"gross": 5000,
"total": 5000
},
"sources": {
"message": {
"gross": 15000,
"total": 15000,
"netTotal": 13000,
"count": 6,
"netCount": 5,
"average": 2500,
"netAverage": 2600
},
"post": {
"gross": 8500,
"total": 8500,
"netTotal": 8500,
"count": 5,
"netCount": 5,
"average": 1700,
"netAverage": 1700
},
"referral": {
"gross": 4200,
"total": 4200,
"netTotal": 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"
}
}
}
},
"/v1/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\nEvery field carries the same meaning as on `GET /insights/fans/{userUuid}`, including which money fields are net of reversals and which are gross, and the same absence of caching.\n\nMaximum 100 fan UUIDs per request. Failed keys are reported as `{ \"error\": \"forbidden\" | \"not_found\" | \"internal\" }`.",
"operationId": "batchFanInsights",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:insights",
"read:fan"
]
}
],
"x-mint": {
"content": "\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"
},
"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": "When this fan last paid this creator (ISO 8601), or null if they never have. Fan-initiated payments only, so an automatic subscription renewal never moves it, and App Store purchases do not count as a purchase here. Reversed purchases are NOT skipped: a purchase later refunded or charged back still counts as the last purchase, because the fan did reach for their wallet at that moment, which makes this recency of intent rather than recency of valid spend. Use `lastValidPurchaseAt` for the latter."
},
"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`, and net of reversals despite the field name."
},
"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. Net of reversals: a refund or chargeback is a separate invoice for the full original amount and is subtracted here, so this is normally lower than the sum of the gross `sources` figures and can be negative. Reversals are selected by their own type rather than by what they reverse, so a clawed-back creator reward the fan never paid for is subtracted here too, and this can fall below what the fan actually paid. It is not the same as `netTotal`, which is aggregated over the surviving purchases instead; the two differ for a purchase reversed without a reversal invoice, which has no negative row for this figure to subtract."
},
"netTotal": {
"type": "number",
"description": "Total this fan paid with refunded and charged-back purchases removed, in USD cents. Aggregated over the surviving purchases themselves, so it and the per-source `netTotal` values describe one set of purchases and add up. It usually equals `total`, which subtracts reversals by counting their negative rows; the two part company only for a reversal recorded on the original purchase without a row of its own, which `total` cannot see."
}
},
"required": [
"gross",
"total",
"netTotal"
]
},
"maxSinglePayment": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`, and excludes reversed purchases."
},
"total": {
"type": "number",
"description": "Largest single payment this fan made, in USD cents. Excludes App Store purchases, as `total` does. Excludes reversed purchases: a payment later refunded or charged back is not eligible, so this can be lower than the largest amount the fan ever paid. Reversal invoices themselves are never counted. This has been the behaviour since July 2025. A refund or chargeback marker on the payment counts as a reversal in its own right when no reversal invoice is linked, so a purchase reversed that way is excluded too; a purchase whose reversal was created and then failed stays eligible, because that reversal never settled."
}
},
"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`, and gross of reversals."
},
"total": {
"type": "number",
"description": "Total amount paid by the fan for this source type, in USD cents. Gross of reversals: a purchase that was later refunded or charged back is still counted here in full. Use `netTotal` for the figure with those purchases removed."
},
"netTotal": {
"type": "number",
"description": "Total paid from this source with refunded and charged-back purchases removed, in USD cents: the sum of the purchases that still stand, and the numerator of `netAverage`. Net of reversals only, not of Fanvue fees, unlike the `net` returned by /insights/earnings and /agencies/insights/*."
},
"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",
"netTotal",
"count",
"netCount",
"average",
"netAverage"
]
},
"description": "Breakdown of this fan's spend by source, keyed by the same source names /insights/earnings uses (so `renewal` is a catch-all for every recurring charge after the first payment). `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. Refunds and chargebacks are never a source entry of their own. Each entry carries both treatments: `total`, `count` and `average` are gross of reversals, so the `total` values do not sum to `total.total` and the difference is exactly the reversals, while `netTotal`, `netCount` and `netAverage` drop the reversed purchases and the `netTotal` values do sum to `total.netTotal`."
}
},
"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": 7000,
"total": 7000,
"netTotal": 7000
},
"maxSinglePayment": {
"gross": 5000,
"total": 5000
},
"sources": {
"subscription": {
"gross": 7000,
"total": 7000,
"netTotal": 7000,
"count": 7,
"netCount": 7,
"average": 1000,
"netAverage": 1000
},
"tips": {
"gross": 5000,
"total": 5000,
"netTotal": 0,
"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"
}
}
}
},
"/v1/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\nMaximum 100 fan UUIDs per request. Failed keys are reported as `{ \"error\": \"not_found\" | \"internal\" }`.",
"operationId": "batchFanProfiles",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:fan"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:fan` — Access fan-related data and information within the platform.\n"
},
"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"
}
}
}
},
"/v1/insights/fans/{userUuid}": {
"get": {
"summary": "Get fan insights",
"description": "Returns detailed insights about a specific fan for the authenticated creator, including spending statistics, subscription status, and fan engagement metrics.\n\nEach money field comes as a gross value and a net one, net meaning refunded and charged-back purchases removed: `total` and `netTotal`, `count` and `netCount`, `average` and `netAverage`. `spending.total.total` has always been net of reversals, so the gross per-source figures can add up to more than it and the gap is exactly the reversals, which are not returned as a source of their own; the per-source `netTotal` values add up to `spending.total.netTotal`. `spending.maxSinglePayment` drops reversed purchases entirely, which is why it carries no net variant.\n\nA reversal is normally a separate invoice for the full original amount: there are no partial refunds, and the original payment is never rewritten, so the original still appears on `/insights/earnings`. Pair the two through `reversedTransactionOrderId` on the `refund`/`chargeback` rows of that endpoint. A payment marked refunded or charged back without a linked reversal invoice is the exception: there is no negative row for `spending.total.total` to subtract so it does not come down, while every net figure drops the purchase. That is why the net total is aggregated over the surviving purchases rather than derived from the gross one.\n\nEvery figure here is computed on each request with no caching — the spending fields from live invoice data, `status` and the `subscription` block from the subscription, follow and payment-method records — so two reads seconds apart can legitimately differ.",
"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": "\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"
},
"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": "When this fan last paid this creator (ISO 8601), or null if they never have. Fan-initiated payments only, so an automatic subscription renewal never moves it, and App Store purchases do not count as a purchase here. Reversed purchases are NOT skipped: a purchase later refunded or charged back still counts as the last purchase, because the fan did reach for their wallet at that moment, which makes this recency of intent rather than recency of valid spend. Use `lastValidPurchaseAt` for the latter."
},
"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`, and net of reversals despite the field name."
},
"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. Net of reversals: a refund or chargeback is a separate invoice for the full original amount and is subtracted here, so this is normally lower than the sum of the gross `sources` figures and can be negative. Reversals are selected by their own type rather than by what they reverse, so a clawed-back creator reward the fan never paid for is subtracted here too, and this can fall below what the fan actually paid. It is not the same as `netTotal`, which is aggregated over the surviving purchases instead; the two differ for a purchase reversed without a reversal invoice, which has no negative row for this figure to subtract."
},
"netTotal": {
"type": "number",
"description": "Total this fan paid with refunded and charged-back purchases removed, in USD cents. Aggregated over the surviving purchases themselves, so it and the per-source `netTotal` values describe one set of purchases and add up. It usually equals `total`, which subtracts reversals by counting their negative rows; the two part company only for a reversal recorded on the original purchase without a row of its own, which `total` cannot see."
}
},
"required": [
"gross",
"total",
"netTotal"
]
},
"maxSinglePayment": {
"type": "object",
"properties": {
"gross": {
"type": "number",
"description": "DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`, and excludes reversed purchases."
},
"total": {
"type": "number",
"description": "Largest single payment this fan made, in USD cents. Excludes App Store purchases, as `total` does. Excludes reversed purchases: a payment later refunded or charged back is not eligible, so this can be lower than the largest amount the fan ever paid. Reversal invoices themselves are never counted. This has been the behaviour since July 2025. A refund or chargeback marker on the payment counts as a reversal in its own right when no reversal invoice is linked, so a purchase reversed that way is excluded too; a purchase whose reversal was created and then failed stays eligible, because that reversal never settled."
}
},
"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`, and gross of reversals."
},
"total": {
"type": "number",
"description": "Total amount paid by the fan for this source type, in USD cents. Gross of reversals: a purchase that was later refunded or charged back is still counted here in full. Use `netTotal` for the figure with those purchases removed."
},
"netTotal": {
"type": "number",
"description": "Total paid from this source with refunded and charged-back purchases removed, in USD cents: the sum of the purchases that still stand, and the numerator of `netAverage`. Net of reversals only, not of Fanvue fees, unlike the `net` returned by /insights/earnings and /agencies/insights/*."
},
"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",
"netTotal",
"count",
"netCount",
"average",
"netAverage"
]
},
"description": "Breakdown of this fan's spend by source, keyed by the same source names /insights/earnings uses (so `renewal` is a catch-all for every recurring charge after the first payment). `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. Refunds and chargebacks are never a source entry of their own. Each entry carries both treatments: `total`, `count` and `average` are gross of reversals, so the `total` values do not sum to `total.total` and the difference is exactly the reversals, while `netTotal`, `netCount` and `netAverage` drop the reversed purchases and the `netTotal` values do sum to `total.netTotal`."
}
},
"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": 25700,
"total": 25700,
"netTotal": 25700
},
"maxSinglePayment": {
"gross": 5000,
"total": 5000
},
"sources": {
"message": {
"gross": 15000,
"total": 15000,
"netTotal": 13000,
"count": 6,
"netCount": 5,
"average": 2500,
"netAverage": 2600
},
"post": {
"gross": 8500,
"total": 8500,
"netTotal": 8500,
"count": 5,
"netCount": 5,
"average": 1700,
"netAverage": 1700
},
"referral": {
"gross": 4200,
"total": 4200,
"netTotal": 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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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"
}
}
}
},
"/v1/media": {
"get": {
"summary": "Get user's media list (cursor-paginated)",
"description": "Cursor-paginated list of the creator's vault media, most recent first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination and dropped `pagination.total`. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent uploads, unlike the offset-paginated v0 endpoint.",
"operationId": "getUserMedia_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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",
"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": "\n **Required scope**\n\n - `read:media` — Access media files, images, videos, and other content assets.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated list of media items",
"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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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\nMaximum 20 media UUIDs per request.",
"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": "\n **Required scope**\n\n - `read:media` — Access media files, images, videos, and other content assets.\n"
},
"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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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"
}
}
}
},
"/v1/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 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.",
"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": "\n **Required scope**\n\n - `read:media` — Access media files, images, videos, and other content assets.\n"
},
"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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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"
}
}
}
},
"/v1/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 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.",
"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": "\n **Required scope**\n\n - `read:media` — Access media files, images, videos, and other content assets.\n"
},
"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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:media` — Access media files, images, videos, and other content assets.\n"
},
"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"
}
}
}
},
"/v1/media-links": {
"get": {
"summary": "List media links (cursor-paginated)",
"description": "List the authenticated creator's media links, newest first, with keyset pagination. Soft-deleted links, and links whose media is no longer available, are excluded. Keyset pagination is stable under concurrent writes and has constant per-page cost, unlike the offset-paginated v0 endpoint. Page with the opaque `nextCursor`. All amounts are integer minor units of the currency (e.g. cents).",
"operationId": "listMediaLinksV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:creator"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"example": {
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://fanvue.com/creator/fvml-3",
"price": 1999,
"mediaUuids": [
"550e8400-e29b-41d4-a716-446655440010"
],
"clicks": 128,
"unlocks": 12,
"earnings": 23988,
"createdAt": "2025-01-16T14:20:00.000Z"
}
],
"nextCursor": "k0FQ1m9yb3ZpZGVkQnlUaGVBUEk",
"total": 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"
}
}
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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\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",
"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": "\n **Required scope**\n\n - `read:self` — Access your own user profile information, including basic account details and settings.\n"
},
"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"
}
}
}
},
"/v1/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\nAccess is limited to approved partner applications. Contact Fanvue to have your application enabled for creator onboarding. Requests are additionally capped per application per day.",
"operationId": "onboardCreator",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"write:creator"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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 (cursor-paginated)",
"description": "Returns a cursor-paginated list of posts created by the authenticated user. Posts are ordered by pinned status first, then by publication date (newest first).\n\nCursor-paginated: page with the opaque `nextCursor` from the previous response. Keyset pagination gives constant-cost pages and, unlike the offset-paginated v0 endpoint, does not shift rows when posts are created or deleted mid-walk.\n\nPosts are ordered on mutable columns, so a post that is pinned, unpinned, or published while you are paging can be returned twice. Treat the walk as at-least-once and de-duplicate on `uuid`.\n\nThe cursor carries the filters it was minted under: when `cursor` is supplied, `includeUnpublished`, `startDate` and `endDate` are ignored and the walk continues over the same set of posts. Change the filters by starting a new walk without a cursor.",
"operationId": "listPostsV1",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"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",
"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": "\n **Required scope**\n\n - `read:post` — Read posts, including post details, comments, likes, and tips.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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": "Posts, pinned first then most recently published first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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": []
}
],
"nextCursor": null,
"total": 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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:post` — Read posts, including post details, comments, likes, and tips.\n"
},
"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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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"
}
}
}
},
"/v1/posts/{uuid}/tips": {
"get": {
"summary": "Get tips for a post (cursor-paginated)",
"description": "Cursor-paginated list of tips received on a specific post, most recent first. Only the post owner can view tips.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent tips, unlike the offset-paginated v0 endpoint.",
"operationId": "getPostTips_v1_experimental",
"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": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:post"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:post` — Read posts, including post details, comments, likes, and tips.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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-15T00:00:00.000Z",
"gross": 2000,
"net": 1700
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": "Post not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"410": {
"$ref": "#/components/responses/SunsetVersionResponse"
},
"429": {
"$ref": "#/components/responses/RateLimitResponse"
}
}
}
},
"/v1/posts/{uuid}/likes": {
"get": {
"summary": "Get likes for a post (cursor-paginated)",
"description": "Cursor-paginated list of likes on a specific post, most recent first. Only the post owner can view likes.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent likes, unlike the offset-paginated v0 endpoint.",
"operationId": "getPostLikes_v1_experimental",
"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": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:post"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:post` — Read posts, including post details, comments, likes, and tips.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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-15T00:00:00.000Z"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": "Post not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"410": {
"$ref": "#/components/responses/SunsetVersionResponse"
},
"429": {
"$ref": "#/components/responses/RateLimitResponse"
}
}
}
},
"/v1/posts/{uuid}/comments": {
"get": {
"summary": "Get comments for a post (cursor-paginated)",
"description": "Cursor-paginated list of comments on a specific post, most recent first. Only the post owner can view comments.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent comments, unlike the offset-paginated v0 endpoint.",
"operationId": "getPostComments_v1_experimental",
"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": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:post"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:post` — Read posts, including post details, comments, likes, and tips.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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, most recent first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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-15T00:00:00.000Z",
"updatedAt": null
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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": "Post not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
}
}
},
"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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:post` — Create, edit, and manage posts and content on behalf of users.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:creator` — Access creator profiles, content, and creator-specific information.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/subscribers": {
"get": {
"summary": "Get subscribers (cursor-paginated)",
"description": "Returns the users who have subscriptions to the authenticated user.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination for both sort modes. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent subscriptions, unlike the offset-paginated v0 endpoint.\n\n\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",
"operationId": "listSubscribers_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"enum": [
"name",
"subscribedAt"
],
"description": "Public field to sort by (default: subscribedAt)"
},
"required": false,
"description": "Public field to sort by (default: subscribedAt)",
"name": "sortField",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort direction (default: desc for subscribedAt, asc for name)"
},
"required": false,
"description": "Sort direction (default: desc for subscribedAt, asc for name)",
"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 `nextCursor`. It carries the sortField, sortDirection and date range the first page was cut under, so later pages need nothing but the cursor. Resending those filters is allowed while they match it; a value that contradicts the cursor is rejected."
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`. It carries the sortField, sortDirection and date range the first page was cut under, so later pages need nothing but the cursor. Resending those filters is allowed while they match it; a value that contradicts the cursor is rejected.",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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"
}
],
"security": [
{
"BearerAuth": [
"read:fan"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:fan` — Access fan-related data and information within the platform.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"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"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:fan` — Access fan-related data and information within the platform.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n"
},
"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//`. 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": "\n **Required scope**\n\n - `write:tracking_links` — Create and delete tracking links.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:tracking_links` — Create and delete tracking links.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n"
},
"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"
}
}
}
},
"/v1/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//fv-3?campaign=spring_launch`), using plain query parameters rather than the `metadata[]` 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": "\n **Required scope**\n\n - `read:tracking_links` — Read tracking links and the users associated with them, including per-user tracking metadata.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:self` — Access your own user profile information, including basic account details and settings.\n"
},
"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",
"description": "Total likes the creator's content has received. Absent for non-creator accounts."
},
"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"
],
"description": "Counts of the creator's posted content by media type. Absent for non-creator accounts."
}
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:self` — Access your own user profile information, including basic account details and settings.\n"
},
"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"
},
"likesCount": {
"type": "number",
"description": "Total likes the creator's content has received. Absent for non-creator accounts."
},
"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"
],
"description": "Counts of the creator's posted content by media type. Absent for non-creator accounts."
},
"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",
"likesCount": 1250,
"contentCounts": {
"imageCount": 145,
"videoCount": 67,
"audioCount": 12,
"postCount": 234,
"payToViewPostCount": 45
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:creator` — Modify creator profiles, settings, and creator-specific data.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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 (cursor-paginated)",
"description": "Cursor-paginated list of the creator's vault folders, oldest first.\n\n**v1-experimental Breaking Change**: Switched from offset-based pagination (`page`/`size`) to keyset cursor pagination and dropped the per-folder `mediaCount`. Page with the opaque `nextCursor`; keyset pagination stays stable under concurrent folder changes, unlike the offset-paginated v0 endpoint.",
"operationId": "listVaultFolders_v1_experimental",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"schema": {
"type": "string",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"name": "cursor",
"in": "query"
},
{
"schema": {
"type": "number",
"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",
"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": "\n **Required scope**\n\n - `read:media` — Access media files, images, videos, and other content assets.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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"
}
},
"required": [
"name",
"createdAt"
]
},
"description": "Array of vault folders, oldest first"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results"
}
},
"required": [
"data",
"nextCursor"
]
},
"example": {
"data": [
{
"name": "Behind the scenes",
"createdAt": "2024-01-13T00:00:00.000Z"
},
{
"name": "Premium sets",
"createdAt": "2024-01-15T00:00:00.000Z"
}
],
"nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}
}
}
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:media` — Access media files, images, videos, and other content assets.\n"
},
"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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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"
}
}
}
},
"/v1/vault/folders/{folderName}/media": {
"get": {
"summary": "List media in folder (cursor-paginated)",
"description": "Returns a cursor-paginated list of media items in the specified folder.\n\nCursor-paginated: page with the opaque `nextCursor` from the previous response. Keyset pagination gives stable pages under concurrent activity, unlike the offset-paginated v0 endpoint: rows are not reshuffled between pages when media is added to or removed from the folder mid-walk. `total` is the count of media in the folder matching the applied filters, measured once when the walk starts.\n\nSorting by `addedAt` is the cheaper ordering — it is served directly by an index on the folder membership. `createdAt` orders by the media row instead, which is not index-served under a folder restriction and costs a sort proportional to the folder's size.\n\nThe cursor carries the ordering and filters it was minted under: when `cursor` is supplied, `sort`, `order`, `mediaType`, `name`, `startDate` and `endDate` are ignored and the walk continues over the same media in the same order. Change any of them by starting a new walk without a cursor. `variants` is not carried, since it only selects which variants are returned for each item.",
"operationId": "listVaultFolderMediaV1",
"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",
"description": "Opaque pagination cursor from a previous response's `nextCursor`"
},
"required": false,
"description": "Opaque pagination cursor from a previous response's `nextCursor`",
"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",
"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": "\n **Required scope**\n\n - `read:media` — Access media files, images, videos, and other content assets.\n"
},
"responses": {
"200": {
"description": "Cursor-paginated 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",
"description": "Variant id. `legacy-` for media not yet backfilled into media_variants."
},
"variantType": {
"type": "string",
"enum": [
"blurred",
"main",
"thumbnail",
"thumbnail_gallery"
]
},
"displayPosition": {
"type": "integer",
"minimum": 0,
"description": "Ordering hint within the item's variants. 0 when the platform did not assign a position (most main, blurred and image thumbnail variants); video and document thumbnails are 1-based."
},
"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 in the folder"
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page, or null when there are no more results"
},
"total": {
"type": [
"number",
"null"
],
"description": "Total number of items, or null when a count is not computed for this list"
}
},
"required": [
"data",
"nextCursor",
"total"
]
},
"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"
}
],
"nextCursor": null,
"total": 2
}
}
}
},
"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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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": "\n **Required scope**\n\n - `write:media` — Upload, modify, and manage media files and content assets. Also required for vault folder management.\n"
},
"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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:self` — Access your own user profile information, including basic account details and settings.\n"
},
"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.mass_sent`, `creator.message.read`, `creator.message.read_by_fan`, `creator.message.reaction`, and `creator.message.deleted`; `read:experience` for the `creator.experience_subscription.*` events.\n\n`creator.experience_subscription.deactivated` fires whenever a fan's paid fan-experience subscription stops granting access — they cancelled and the period ran out, a renewal failed, the charge was refunded or charged back, or we or the creator ended it. Act on `access_ends_at`, the moment access was revoked, which is not always `expires_at` (a refund, chargeback, ban or unpublish ends access mid-period). A cancellation on its own does not fire it, because access continues to period end. Treat `expires_at` as a deadline in its own right rather than waiting only for this event: access also lapses on the clock when a renewal is still settling or an upstream lookup fails, and nothing is sent until a later hourly sweep resolves the subscription.\n\nPair it with `creator.experience_subscription.activated`, which fires when access starts: `activation_reason` is `subscribed` on the fan's initial purchase and `renewal_recovered` when a renewal charge that had already failed is recovered by a later retry. Handling the recovery case is required if you act on the deactivated event, because a failed renewal revokes access before the retries that may still pay for the period are exhausted.\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.\n\nMass messages are delivered on `creator.message.mass_sent`, never on `creator.message.sent`, so subscribe to both to see every creator-to-fan send. Splitting them lets a subscriber take 1:1 messages without a broadcast fan-out that can reach tens of thousands of events for one send. A mass message is one message delivered to many conversations, so every recipient's event carries the same message `uuid` with a different `fan`: key it on the pair. `text` arrives already personalised for that recipient.",
"operationId": "createWebhookSubscription",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:self"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:self` — Access your own user profile information, including basic account details and settings.\n"
},
"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.experience_subscription.deactivated",
"creator.experience_subscription.activated",
"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.mass_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"
}
}
}
},
"/v1/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": "\n **Required scope**\n\n - `read:self` — Access your own user profile information, including basic account details and settings.\n"
},
"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"
}
}
}
},
"/v1/webhooks/test": {
"post": {
"summary": "Send a test webhook event",
"description": "Deliver a synthetic event of the given type to your own subscriptions, so you can build and verify a handler without waiting for a real one to occur.\n\nThe delivery is indistinguishable from a genuine event: same envelope, same signature, same retry behaviour. Only the values inside `data` are synthetic, and identifiers are prefixed with `TEST-`.\n\nYou must already have an active subscription for the requested event; this endpoint delivers to the URLs you registered and cannot be pointed at any other. Every subscription covering the event receives the delivery, exactly as a real event would. The token must hold the same scope subscribing to that event requires.",
"operationId": "sendTestWebhook",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"security": [
{
"BearerAuth": [
"read:self"
]
}
],
"x-mint": {
"content": "\n **Required scope**\n\n - `read:self` — Access your own user profile information, including basic account details and settings.\n"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"event": {
"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",
"creator.payment.succeeded",
"creator.subscription.activated",
"creator.subscription.renewed",
"creator.subscription.deactivated",
"creator.subscription.cancel_at_period_end_changed",
"creator.experience_subscription.deactivated",
"creator.experience_subscription.activated",
"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.mass_sent",
"creator.message.read",
"creator.message.read_by_fan"
],
"description": "The platform event to deliver. Deprecated flat events cannot be tested."
}
},
"required": [
"event"
]
}
}
}
},
"responses": {
"202": {
"description": "Test event accepted for delivery",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "ID of the delivered test event. Matches the `id` in the delivered envelope, so you can correlate this response with what arrives at your endpoint."
},
"event": {
"type": "string",
"description": "The platform event that was delivered"
}
},
"required": [
"id",
"event"
]
},
"example": {
"id": "4f6c1f8a-2b9d-4c3e-9f1a-7d8e5c2b4a10",
"event": "checkout_link.payment.succeeded"
}
}
}
},
"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": {}
}