Charfeed API

auth

post/v1/auth/sign-up

Create a Cognito account with email and password

Request body

application/json

emailstringrequired

passwordstringrequired

Responses

application/json

idTokenstringrequired

refreshTokenstringrequired

expiresInintegerrequired

localIdstringrequired

isNewUserboolean

curl

curl -X POST '/v1/auth/sign-up' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com",
  "password": "string"
}'

Try it

Request body (JSON)

post/v1/auth/sign-in

Exchange email and password for Cognito tokens

Request body

application/json

emailstringrequired

passwordstringrequired

Responses

application/json

idTokenstringrequired

refreshTokenstringrequired

expiresInintegerrequired

localIdstringrequired

isNewUserboolean

curl

curl -X POST '/v1/auth/sign-in' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com",
  "password": "string"
}'

Try it

Request body (JSON)

post/v1/auth/refresh

Exchange a refresh token for a fresh idToken

Request body

application/json

refreshTokenstringrequired

Responses

application/json

idTokenstringrequired

refreshTokenstringrequired

expiresInintegerrequired

localIdstringrequired

isNewUserboolean

post/v1/auth/send-password-reset

Trigger the password-reset email

Always returns 204 — does not disclose whether the email is registered.

Request body

application/json

emailstringrequired

Responses

No response body

post/v1/auth/send-email-verification Auth required

Trigger the email-verification email

Responses

No response body

blocks

get/v1/users/me/blocks Auth required

List the caller's blocked users (paginated, newest first)

Parameters

query parameters

cursor

string

pageSize

integerdefault: 20

Responses

application/json

itemsarray<object>required

array

items:

uidstringrequired

handlestringrequired

displayNamestringrequirednullable

avatarUrlstringrequirednullable

blockedAtstringrequired

nextCursorstringrequirednullable

post/v1/users/me/blocks Auth required

Block a user (idempotent — re-block returns existing record)

Parameters

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

targetUidstringrequired

Responses

application/json

blockedUidstringrequired

blockedAtstringrequired

isNewbooleanrequired

curl

curl -X POST '/v1/users/me/blocks' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "targetUid": "string"
}'

Try it

Idempotency-Keyheaderrequired

Request body (JSON)

delete/v1/users/me/blocks/{targetUid} Auth required

Unblock a user (no-op if not blocked)

Parameters

path parameters

targetUidrequired

string

Responses

application/json

removedbooleanrequired

characters

post/v1/characters Auth required

Create a new character (pending status)

Parameters

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

handlestringrequired

displayNamestringrequired

biostringnullable

avatarUrlstringnullable

coverUrlstringnullable

avatarUploadIdstring

coverUploadIdstring

tagsarray<string>

arraydefault: []

items:

string

contentTypesarray<string>required

array

items:

string

worldstringnullable

Responses

application/json

characterIdstringrequired

handlestringrequired

statusstringrequired

"pending""approved""rejected"

curl

curl -X POST '/v1/characters' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "handle": "string",
  "displayName": "string",
  "bio": "string",
  "avatarUrl": "string",
  "coverUrl": "string",
  "avatarUploadId": "string",
  "coverUploadId": "string",
  "tags": [
    "string"
  ],
  "contentTypes": [
    "ai"
  ],
  "world": "string"
}'

Try it

Idempotency-Keyheaderrequired

Request body (JSON)

get/v1/characters/by-id/{id}

Get character by id

Parameters

path parameters

idrequired

string

Responses

application/json

idstringrequired

handlestringrequired

displayNamestringrequired

biostringrequirednullable

avatarUrlstringrequirednullable

coverUrlstringrequirednullable

tagsarray<string>required

array

items:

string

contentTypesarray<string>required

array

items:

string

worldstringrequirednullable

hasActiveTiersbooleanrequired

countersobjectrequired

followersintegerrequired

subscribersintegerrequired

postsintegerrequired

verifiedbooleanrequired

featuredbooleanrequired

visibilitystringrequired

"public""private"

interactionsRestrictedstringrequired

"public""subscribers_only"

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

createdAtstringrequired

updatedAtstringrequired

statusstring

"pending""approved""rejected"

commissionBpsinteger

commissionValidUntilstringnullable

ownerIdsarray<string>

array

items:

string

primaryOwnerIdstring

payoutAccountIdstringnullable

suspendedboolean

featuredRankintegernullable

chatModelstring

"haiku-4-5""sonnet-4-6""opus-4-7"

get/v1/characters/by-handle/{handle}

Get character by handle

Parameters

path parameters

handlerequired

string

Responses

application/json

idstringrequired

handlestringrequired

displayNamestringrequired

biostringrequirednullable

avatarUrlstringrequirednullable

coverUrlstringrequirednullable

tagsarray<string>required

array

items:

string

contentTypesarray<string>required

array

items:

string

worldstringrequirednullable

hasActiveTiersbooleanrequired

countersobjectrequired

followersintegerrequired

subscribersintegerrequired

postsintegerrequired

verifiedbooleanrequired

featuredbooleanrequired

visibilitystringrequired

"public""private"

interactionsRestrictedstringrequired

"public""subscribers_only"

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

createdAtstringrequired

updatedAtstringrequired

statusstring

"pending""approved""rejected"

commissionBpsinteger

commissionValidUntilstringnullable

ownerIdsarray<string>

array

items:

string

primaryOwnerIdstring

payoutAccountIdstringnullable

suspendedboolean

featuredRankintegernullable

chatModelstring

"haiku-4-5""sonnet-4-6""opus-4-7"

get/v1/characters/{id}/tiers

List character tiers (active by default; owner/admin may include inactive)

Parameters

path parameters

idrequired

string

query parameters

includeInactiverequired

one of:

string

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

characterIdstringrequired

namestringrequired

descriptionstringrequirednullable

priceAmountintegerrequired

currencystringrequired

activebooleanrequired

orderintegerrequired

stripePriceIdstringrequired

subscribersCountintegerrequired

mrrCentsintegerrequired

get/v1/characters/{id}/dashboard Auth required

Aggregated creator-dashboard summary (owner or admin only) — replaces the four-fetch pattern

Parameters

path parameters

idrequired

string

Responses

application/json

characterIdstringrequired

mrrCentsintegerrequired

mrrDeltaPctnumberrequired

subscribersCountintegerrequired

subscribersDeltaintegerrequired

postsThisMonthintegerrequired

postsDeltaintegerrequired

arpuCentsintegerrequired

churnRatenumberrequired

tipsCentsintegerrequired

nextPayoutCentsintegerrequired

nextPayoutAtstringrequirednullable

topPostsarray<object>required

array

items:

postIdstringrequired

thumbnailUrlstringrequirednullable

captionstringrequirednullable

likesintegerrequired

unlocksintegerrequired

revenueCentsintegerrequired

patch/v1/characters/{id} Auth required

Update character fields (owner or admin only)

Parameters

path parameters

idrequired

string

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

displayNamestring

biostringnullable

avatarUrlstringnullable

coverUrlstringnullable

tagsarray<string>

array

items:

string

worldstringnullable

visibilitystring

"public""private"

interactionsRestrictedstring

"public""subscribers_only"

chatModelstring

"haiku-4-5""sonnet-4-6""opus-4-7"

Responses

application/json

successbooleanrequired

updatedAtintegerrequired

curl

curl -X PATCH '/v1/characters/{id}' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "displayName": "string",
  "bio": "string",
  "avatarUrl": "string",
  "coverUrl": "string",
  "tags": [
    "string"
  ],
  "world": "string",
  "visibility": "public",
  "interactionsRestricted": "public",
  "chatModel": "haiku-4-5"
}'

Try it

idpathrequired

Idempotency-Keyheaderrequired

Request body (JSON)

chat-sales

post/v1/chat/offers/{offerId}/accept Auth required

Accept a chat offer — creates Stripe payment surface

Parameters

path parameters

offerIdrequired

string

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

returnUrlstring

cancelUrlstring

Responses

application/json

surfacestringrequired

"checkout""payment_intent"

offerIdstringrequired

checkoutUrlstringrequirednullable

sessionIdstringrequirednullable

clientSecretstringrequirednullable

paymentIntentIdstringrequirednullable

curl

curl -X POST '/v1/chat/offers/{offerId}/accept' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "returnUrl": "string",
  "cancelUrl": "string"
}'

Try it

offerIdpathrequired

Idempotency-Keyheaderrequired

Request body (JSON)

post/v1/chat/offers/{offerId}/decline Auth required

Decline a chat offer

Parameters

path parameters

offerIdrequired

string

header parameters

Idempotency-Keyrequired

UUID v4

string

Responses

application/json

successbooleanrequired

offerIdstringrequired

curl

curl -X POST '/v1/chat/offers/{offerId}/decline' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}'

Try it

offerIdpathrequired

Idempotency-Keyheaderrequired

get/v1/chat/preferences Auth required

Get the caller's chat-sales preferences

Responses

application/json

fewerOffersGlobalbooleanrequired

fewerOffersPerCharacterobjectrequired

patch/v1/chat/preferences Auth required

Update the caller's chat-sales preferences

Parameters

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

fewerOffersGlobalboolean

fewerOffersPerCharacterobject

Responses

application/json

fewerOffersGlobalbooleanrequired

fewerOffersPerCharacterobjectrequired

curl

curl -X PATCH '/v1/chat/preferences' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "fewerOffersGlobal": false,
  "fewerOffersPerCharacter": {}
}'

Try it

Idempotency-Keyheaderrequired

Request body (JSON)

get/v1/characters/{characterId}/chat-revenue Auth required

Get chat-attributed revenue for a character (owner or admin only)

Parameters

path parameters

characterIdrequired

string

query parameters

from

stringdate-time

to

stringdate-time

Responses

application/json

characterIdstringrequired

totalAmountGrossintegerrequired

totalCountintegerrequired

currencystringrequired

byOfferKindobjectrequired

bucketsarray<object>required

array

items:

datestringrequired

offerKindstringrequired

"tier_subscribe""post_unlock""tip""paid_dm"

countintegerrequired

amountGrossintegerrequired

currencystringrequired

get/v1/characters/{characterId}/chat-sales-config Auth required

Get a character's chat-sales config (owner only)

Parameters

path parameters

characterIdrequired

string

Responses

application/json

enabledOfferKindsarray<string>required

array

items:

string

aggressivenessanyrequired

patch/v1/characters/{characterId}/chat-sales-config Auth required

Update a character's chat-sales config (owner only)

Parameters

path parameters

characterIdrequired

string

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

enabledOfferKindsarray<string>

array

items:

string

aggressivenessany

Responses

application/json

enabledOfferKindsarray<string>required

array

items:

string

aggressivenessanyrequired

curl

curl -X PATCH '/v1/characters/{characterId}/chat-sales-config' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabledOfferKinds": [
    "tier_subscribe"
  ],
  "aggressiveness": null
}'

Try it

characterIdpathrequired

Idempotency-Keyheaderrequired

Request body (JSON)

posts

post/v1/posts Auth required

Create a new post

Parameters

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

characterIdstringrequired

accessstringrequired

"free""tier"

minTierIdstringnullable

ratingstring

"sfw""suggestive""nsfw"

mediaRefsarray<object>required

array

items:

uploadIdstringrequired

kindstringrequired

"image""video"

captionstringnullable

tagsarray<string>

arraydefault: []

items:

string

Responses

application/json

postIdstringrequired

createdAtintegerrequired

curl

curl -X POST '/v1/posts' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "characterId": "string",
  "access": "free",
  "minTierId": "string",
  "rating": "sfw",
  "mediaRefs": [
    {
      "uploadId": "00000000-0000-0000-0000-000000000000",
      "kind": "image"
    }
  ],
  "caption": "string",
  "tags": [
    "string"
  ]
}'

Try it

Idempotency-Keyheaderrequired

Request body (JSON)

get/v1/posts/{id}

Get post by id (preview URLs only)

Parameters

path parameters

idrequired

string

Responses

application/json

idstringrequired

characterIdstringrequired

characterobjectrequired

idstringrequired

handlestringrequired

displayNamestringrequired

avatarUrlstringrequirednullable

verifiedbooleanrequired

contentTypesarray<string>

array

items:

string

primaryOwnerIdstringrequirednullable

interactionsRestrictedstringrequired

"public""subscribers_only"

followersCountintegerrequired

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

premiumPostsCountintegerrequired

accessstringrequired

"free""tier"

minTierIdstringrequirednullable

ratingstringrequired

"sfw""suggestive""nsfw"

mediaarray<object>required

array

items:

kindstringrequired

"image""video"

previewUrlstringrequirednullable

widthintegerrequired

heightintegerrequired

durationMsintegernullable

transcodeStatusstringnullable

"pending""processing""ready""failed"

captionstringrequirednullable

tagsarray<string>required

array

items:

string

countersobjectrequired

likesintegerrequired

commentsintegerrequired

repostsintegerrequired

viewsintegerrequired

featuredbooleanrequired

processingStatusstringrequired

"processing""ready""failed"

ownerIdsarray<string>

array

items:

string

createdAtstringrequired

updatedAtstringrequired

patch/v1/posts/{id} Auth required

Update post fields (owner or admin)

Parameters

path parameters

idrequired

string

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

captionstringnullable

tagsarray<string>

array

items:

string

accessstring

"free""tier"

minTierIdstringnullable

ratingstring

"sfw""suggestive""nsfw"

deletedboolean

featuredboolean

Responses

application/json

successbooleanrequired

updatedAtintegerrequired

curl

curl -X PATCH '/v1/posts/{id}' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "caption": "string",
  "tags": [
    "string"
  ],
  "access": "free",
  "minTierId": "string",
  "rating": "sfw",
  "deleted": false,
  "featured": false
}'

Try it

idpathrequired

Idempotency-Keyheaderrequired

Request body (JSON)

comments

get/v1/posts/{postId}/comments

List non-deleted comments on a post

Parameters

path parameters

postIdrequired

string

query parameters

cursor

string

pageSize

integerdefault: 20

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

authorKindstringrequired

"user""character"

authorIdstringrequired

authorHandlestringrequired

authorDisplayNamestringrequired

authorAvatarUrlstringrequirednullable

textstringrequired

replyToIdstringrequirednullable

likeCountintegerrequired

createdAtstringrequired

nextCursorstringrequirednullable

post/v1/posts/{postId}/comments Auth required

Create a comment on a post

Parameters

path parameters

postIdrequired

string

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

textstringrequired

replyToIdstringnullable

authorCharacterIdstring

Responses

application/json

commentIdstringrequired

postIdstringrequired

createdAtintegerrequired

curl

curl -X POST '/v1/posts/{postId}/comments' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "string",
  "replyToId": "string",
  "authorCharacterId": "string"
}'

Try it

postIdpathrequired

Idempotency-Keyheaderrequired

Request body (JSON)

delete/v1/posts/{postId}/comments/{commentId} Auth required

Soft-delete a comment (author, owner, or admin)

Parameters

path parameters

postIdrequired

string

commentIdrequired

string

header parameters

Idempotency-Keyrequired

UUID v4

string

Responses

application/json

successbooleanrequired

curl

curl -X DELETE '/v1/posts/{postId}/comments/{commentId}' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}'

Try it

postIdpathrequired

commentIdpathrequired

Idempotency-Keyheaderrequired

likes

get/v1/posts/{postId}/likes/status Auth required

Check whether the current user has liked a post

Parameters

path parameters

postIdrequired

string

Responses

application/json

likedbooleanrequired

post/v1/posts/{postId}/likes Auth required

Like a post (idempotent)

Parameters

path parameters

postIdrequired

string

Responses

application/json

successbooleanrequired

likedbooleanrequired

post/v1/posts/{postId}/likes/unlike Auth required

Unlike a post (idempotent)

Parameters

path parameters

postIdrequired

string

Responses

application/json

successbooleanrequired

likedbooleanrequired

feeds

get/v1/feeds/home Auth required

Personalized home feed from followed characters

Parameters

query parameters

cursor

string

pageSize

integerdefault: 20

mode

stringdefault: "for-you"

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

characterIdstringrequired

characterobjectrequired

idstringrequired

handlestringrequired

displayNamestringrequired

avatarUrlstringrequirednullable

verifiedbooleanrequired

contentTypesarray<string>

array

items:

string

primaryOwnerIdstringrequirednullable

interactionsRestrictedstringrequired

"public""subscribers_only"

followersCountintegerrequired

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

premiumPostsCountintegerrequired

accessstringrequired

"free""tier"

minTierIdstringrequirednullable

ratingstringrequired

"sfw""suggestive""nsfw"

mediaarray<object>required

array

items:

kindstringrequired

"image""video"

previewUrlstringrequirednullable

widthintegerrequired

heightintegerrequired

durationMsintegernullable

transcodeStatusstringnullable

"pending""processing""ready""failed"

captionstringrequirednullable

tagsarray<string>required

array

items:

string

countersobjectrequired

likesintegerrequired

commentsintegerrequired

repostsintegerrequired

viewsintegerrequired

featuredbooleanrequired

processingStatusstringrequired

"processing""ready""failed"

ownerIdsarray<string>

array

items:

string

createdAtstringrequired

updatedAtstringrequired

nextCursorstringrequirednullable

get/v1/feeds/featured-characters

Public featured characters list

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

handlestringrequired

displayNamestringrequired

biostringrequirednullable

avatarUrlstringrequirednullable

coverUrlstringrequirednullable

tagsarray<string>required

array

items:

string

contentTypesarray<string>required

array

items:

string

worldstringrequirednullable

hasActiveTiersbooleanrequired

countersobjectrequired

followersintegerrequired

subscribersintegerrequired

postsintegerrequired

verifiedbooleanrequired

featuredbooleanrequired

visibilitystringrequired

"public""private"

interactionsRestrictedstringrequired

"public""subscribers_only"

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

createdAtstringrequired

updatedAtstringrequired

statusstring

"pending""approved""rejected"

commissionBpsinteger

commissionValidUntilstringnullable

ownerIdsarray<string>

array

items:

string

primaryOwnerIdstring

payoutAccountIdstringnullable

suspendedboolean

featuredRankintegernullable

chatModelstring

"haiku-4-5""sonnet-4-6""opus-4-7"

get/v1/feeds/featured-posts

Public featured posts list (Explore hero carousel)

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

characterIdstringrequired

characterobjectrequired

idstringrequired

handlestringrequired

displayNamestringrequired

avatarUrlstringrequirednullable

verifiedbooleanrequired

contentTypesarray<string>

array

items:

string

primaryOwnerIdstringrequirednullable

interactionsRestrictedstringrequired

"public""subscribers_only"

followersCountintegerrequired

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

premiumPostsCountintegerrequired

accessstringrequired

"free""tier"

minTierIdstringrequirednullable

ratingstringrequired

"sfw""suggestive""nsfw"

mediaarray<object>required

array

items:

kindstringrequired

"image""video"

previewUrlstringrequirednullable

widthintegerrequired

heightintegerrequired

durationMsintegernullable

transcodeStatusstringnullable

"pending""processing""ready""failed"

captionstringrequirednullable

tagsarray<string>required

array

items:

string

countersobjectrequired

likesintegerrequired

commentsintegerrequired

repostsintegerrequired

viewsintegerrequired

featuredbooleanrequired

processingStatusstringrequired

"processing""ready""failed"

ownerIdsarray<string>

array

items:

string

createdAtstringrequired

updatedAtstringrequired

get/v1/feeds/characters/{characterId}/posts

Posts from a specific character with access filter

Parameters

path parameters

characterIdrequired

string

query parameters

cursor

string

pageSize

integerdefault: 20

accessFilter

stringdefault: "all"

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

characterIdstringrequired

characterobjectrequired

idstringrequired

handlestringrequired

displayNamestringrequired

avatarUrlstringrequirednullable

verifiedbooleanrequired

contentTypesarray<string>

array

items:

string

primaryOwnerIdstringrequirednullable

interactionsRestrictedstringrequired

"public""subscribers_only"

followersCountintegerrequired

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

premiumPostsCountintegerrequired

accessstringrequired

"free""tier"

minTierIdstringrequirednullable

ratingstringrequired

"sfw""suggestive""nsfw"

mediaarray<object>required

array

items:

kindstringrequired

"image""video"

previewUrlstringrequirednullable

widthintegerrequired

heightintegerrequired

durationMsintegernullable

transcodeStatusstringnullable

"pending""processing""ready""failed"

captionstringrequirednullable

tagsarray<string>required

array

items:

string

countersobjectrequired

likesintegerrequired

commentsintegerrequired

repostsintegerrequired

viewsintegerrequired

featuredbooleanrequired

processingStatusstringrequired

"processing""ready""failed"

ownerIdsarray<string>

array

items:

string

createdAtstringrequired

updatedAtstringrequired

nextCursorstringrequirednullable

get/v1/feeds/explore/characters

Discovery feed of characters (trending or recent)

Parameters

query parameters

sort

stringdefault: "trending"

contentType

string

cursor

string

pageSize

integerdefault: 20

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

handlestringrequired

displayNamestringrequired

biostringrequirednullable

avatarUrlstringrequirednullable

coverUrlstringrequirednullable

tagsarray<string>required

array

items:

string

contentTypesarray<string>required

array

items:

string

worldstringrequirednullable

hasActiveTiersbooleanrequired

countersobjectrequired

followersintegerrequired

subscribersintegerrequired

postsintegerrequired

verifiedbooleanrequired

featuredbooleanrequired

visibilitystringrequired

"public""private"

interactionsRestrictedstringrequired

"public""subscribers_only"

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

createdAtstringrequired

updatedAtstringrequired

statusstring

"pending""approved""rejected"

commissionBpsinteger

commissionValidUntilstringnullable

ownerIdsarray<string>

array

items:

string

primaryOwnerIdstring

payoutAccountIdstringnullable

suspendedboolean

featuredRankintegernullable

chatModelstring

"haiku-4-5""sonnet-4-6""opus-4-7"

nextCursorstringrequirednullable

follows

post/v1/follows Auth required

Follow a character (idempotent)

Request body

application/json

characterIdstringrequired

Responses

application/json

successbooleanrequired

followingbooleanrequired

curl

curl -X POST '/v1/follows' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "characterId": "string"
}'

Try it

Request body (JSON)

post/v1/follows/unfollow Auth required

Unfollow a character (idempotent)

Request body

application/json

characterIdstringrequired

Responses

application/json

successbooleanrequired

followingbooleanrequired

curl

curl -X POST '/v1/follows/unfollow' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "characterId": "string"
}'

Try it

Request body (JSON)

notifications

get/v1/notifications Auth required

List notifications for the current user

Parameters

query parameters

cursor

string

pageSize

integerdefault: 20

unreadOnlyrequired

one of:

string

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

typestringrequired

"follow""subscribe""unsubscribe""subscription_renewed""comment""like""repost""mentioned""post""tip_received""chat_message""payout_completed""payment_failed""character_approved""character_rejected""post_transcode_failed""system"

fromUserIdstringrequirednullable

fromCharacterIdstringrequirednullable

targetPostIdstringrequirednullable

targetCharacterIdstringrequirednullable

fromUserobjectrequirednullable

uidstringrequired

handlestringrequired

displayNamestringrequired

avatarUrlstringrequirednullable

targetPostobjectrequirednullable

idstringrequired

thumbnailUrlstringrequirednullable

readbooleanrequired

createdAtstringrequired

nextCursorstringrequirednullable

unreadCountintegerrequired

post/v1/notifications/mark-all-read Auth required

Mark all notifications as read

Responses

application/json

successbooleanrequired

updatedCountintegerrequired

post/v1/notifications/{id}/read Auth required

Mark a single notification as read

Parameters

path parameters

idrequired

string

Responses

application/json

successbooleanrequired

post/v1/notifications/push-tokens Auth required

Register or refresh an FCM/APNs push token for this device (upsert by deviceId)

Parameters

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

platformstringrequired

"ios""android""web"

tokenstringrequired

deviceIdstringrequired

deviceMetastringnullable

Responses

application/json

successbooleanrequired

createdbooleanrequired

curl

curl -X POST '/v1/notifications/push-tokens' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "platform": "ios",
  "token": "string",
  "deviceId": "string",
  "deviceMeta": "string"
}'

Try it

Idempotency-Keyheaderrequired

Request body (JSON)

post/v1/notifications/push-tokens/unregister Auth required

Remove the push token for a device (called on sign-out)

Parameters

header parameters

Idempotency-Keyrequired

UUID v4

string

Request body

application/json

deviceIdstringrequired

Responses

application/json

successbooleanrequired

curl

curl -X POST '/v1/notifications/push-tokens/unregister' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Idempotency-Key: {Idempotency-Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "deviceId": "string"
}'

Try it

Idempotency-Keyheaderrequired

Request body (JSON)

reposts

get/v1/posts/{postId}/reposts/status Auth required

Check whether the current user has reposted a post

Parameters

path parameters

postIdrequired

string

Responses

application/json

repostedbooleanrequired

post/v1/posts/{postId}/reposts Auth required

Repost a post (idempotent)

Parameters

path parameters

postIdrequired

string

Responses

application/json

successbooleanrequired

repostedbooleanrequired

post/v1/posts/{postId}/reposts/unrepost Auth required

Undo a repost (idempotent)

Parameters

path parameters

postIdrequired

string

Responses

application/json

successbooleanrequired

repostedbooleanrequired

subscriptions

get/v1/subscriptions/mine Auth required

List current user's active subscriptions

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

characterIdstringrequired

characterobjectrequired

idstringrequired

handlestringrequired

displayNamestringrequired

avatarUrlstringrequirednullable

verifiedbooleanrequired

contentTypesarray<string>

array

items:

string

primaryOwnerIdstringrequirednullable

interactionsRestrictedstringrequired

"public""subscribers_only"

tierIdstringrequired

tierNamestringrequired

subscribersCountintegerrequired

statusstringrequired

currentPeriodStartstringrequired

currentPeriodEndstringrequired

cancelAtPeriodEndbooleanrequired

canceledAtstringrequirednullable

priceAmountintegerrequired

currencystringrequired

stripePaymentMethodobjectrequirednullable

brandstringrequired

last4stringrequired

createdAtstringrequired

users

get/v1/users/me Auth required

Get current user's profile (404 if signup not completed)

Responses

application/json

uidstringrequired

handlestringrequired

emailstringrequirednullable

displayNamestringrequired

biostringrequirednullable

avatarUrlstringrequirednullable

characterIdsarray<string>required

array

items:

string

stripeAccountIdstringrequirednullable

stripeAccountStatusstringrequired

"pending""active""restricted""disabled"

prefsobjectrequired

showSuggestivebooleanrequired

showNsfwbooleanrequired

matureChatEnabledbooleanrequired

suspendedbooleanrequired

ageVerifiedbooleanrequired

acceptedTermsVersionstringrequired

createdAtstringrequired

handleChangedAtstringrequirednullable

handleChangeAvailableAtstringrequirednullable

accountStatusstring

"active""pending_deletion"

scheduledDeletionAtstringnullable

stripeOnboardingobjectnullable

statestringrequired

"new""in_flow""verifying""charging_enabled_review""active""review_timeout""setup_incomplete""account_link_expired"

chargesEnabledbooleanrequired

payoutsEnabledbooleanrequired

pollingUntilstringnullable

connectBalanceintegerrequirednullable

patch/v1/users/me Auth required

Update displayName and/or bio — server-side moderated. Empty bio clears the column.

Request body

application/json

displayNamestring

biostringnullable

avatarUploadIdstring

Responses

application/json

displayNamestringrequired

biostringrequirednullable

avatarUrlstringrequirednullable

curl

curl -X PATCH '/v1/users/me' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "displayName": "string",
  "bio": "string",
  "avatarUploadId": "string"
}'

Try it

Request body (JSON)

post/v1/users/me/accept-tos Auth required

Accept the current ToS version. Pair with the §7.42 modal's 'Accept and continue' CTA.

Request body

application/json

versionstringrequired

Responses

No response body

curl

curl -X POST '/v1/users/me/accept-tos' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "version": "string"
}'

Try it

Request body (JSON)

patch/v1/users/me/handle Auth required

Change the current user's handle (free, 30-day cooldown; old handle reserved for 30 days)

Request body

application/json

handlestringrequired

Responses

application/json

handlestringrequired

handleChangedAtstringrequired

handleChangeAvailableAtstringrequired

curl

curl -X PATCH '/v1/users/me/handle' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "handle": "string"
}'

Try it

Request body (JSON)

get/v1/users/me/characters Auth required

List characters owned by the current user (full view)

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

handlestringrequired

displayNamestringrequired

biostringrequirednullable

avatarUrlstringrequirednullable

coverUrlstringrequirednullable

tagsarray<string>required

array

items:

string

contentTypesarray<string>required

array

items:

string

worldstringrequirednullable

hasActiveTiersbooleanrequired

countersobjectrequired

followersintegerrequired

subscribersintegerrequired

postsintegerrequired

verifiedbooleanrequired

featuredbooleanrequired

visibilitystringrequired

"public""private"

interactionsRestrictedstringrequired

"public""subscribers_only"

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

createdAtstringrequired

updatedAtstringrequired

statusstring

"pending""approved""rejected"

commissionBpsinteger

commissionValidUntilstringnullable

ownerIdsarray<string>

array

items:

string

primaryOwnerIdstring

payoutAccountIdstringnullable

suspendedboolean

featuredRankintegernullable

chatModelstring

"haiku-4-5""sonnet-4-6""opus-4-7"

get/v1/users/me/follows Auth required

List characters followed by the current user

Parameters

query parameters

cursor

string

pageSize

integerdefault: 20

Responses

application/json

itemsarray<object>required

array

items:

characterIdstringrequired

followedAtstringrequired

characterobjectrequired

idstringrequired

handlestringrequired

displayNamestringrequired

avatarUrlstringrequirednullable

verifiedbooleanrequired

contentTypesarray<string>

array

items:

string

primaryOwnerIdstringrequirednullable

interactionsRestrictedstringrequired

"public""subscribers_only"

nextCursorstringrequirednullable

get/v1/users/me/reposts Auth required

List posts the current user has reposted, newest-first

Parameters

query parameters

cursor

string

pageSize

integerdefault: 20

Responses

application/json

itemsarray<object>required

array

items:

postobjectrequired

idstringrequired

characterIdstringrequired

characterobjectrequired

idstringrequired

handlestringrequired

displayNamestringrequired

avatarUrlstringrequirednullable

verifiedbooleanrequired

contentTypesarray<string>

array

items:

string

primaryOwnerIdstringrequirednullable

interactionsRestrictedstringrequired

"public""subscribers_only"

followersCountintegerrequired

cheapestTierobjectrequirednullable

priceCentsintegerrequired

currencystringrequired

premiumPostsCountintegerrequired

accessstringrequired

"free""tier"

minTierIdstringrequirednullable

ratingstringrequired

"sfw""suggestive""nsfw"

mediaarray<object>required

array

items:

kindstringrequired

"image""video"

previewUrlstringrequirednullable

widthintegerrequired

heightintegerrequired

durationMsintegernullable

transcodeStatusstringnullable

"pending""processing""ready""failed"

captionstringrequirednullable

tagsarray<string>required

array

items:

string

countersobjectrequired

likesintegerrequired

commentsintegerrequired

repostsintegerrequired

viewsintegerrequired

featuredbooleanrequired

processingStatusstringrequired

"processing""ready""failed"

ownerIdsarray<string>

array

items:

string

createdAtstringrequired

updatedAtstringrequired

repostedAtstringrequired

nextCursorstringrequirednullable

get/v1/users/me/chat-balance Auth required

Get the caller's chat credits balance (404 if never topped up yet)

Responses

application/json

ownerUidstringrequired

amountMinorintegerrequired

currencystringrequired

updatedAtstringrequired

get/v1/users/me/chat-counters Auth required

List the caller's daily chat-cost counters, newest-first (page size ≤60)

Parameters

query parameters

from

string

to

string

pageSize

integerdefault: 30

Responses

application/json

itemsarray<object>required

array

items:

idstringrequired

ownerUidstringrequired

characterIdstringrequired

dayKeystringrequired

costMinorintegerrequired

inputTokensintegerrequired

outputTokensintegerrequired

messageCountintegerrequired

currencystringrequired

post/v1/users/me/delete-request Auth required

Schedule account deletion: flips account_status to pending_deletion with a 30-day grace period (spec §3.7)

Request body

application/json

acknowledgmentsobjectrequired

forfeitConnectBalanceboolean

cancelSubscriptionsImmediatelyboolean

reasonstring

handleConfirmationstringrequired

Responses

application/json

scheduledDeletionAtstringrequired

curl

curl -X POST '/v1/users/me/delete-request' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "acknowledgments": {},
  "forfeitConnectBalance": false,
  "cancelSubscriptionsImmediately": false,
  "reason": "string",
  "handleConfirmation": "string"
}'

Try it

Request body (JSON)

post/v1/users/me/cancel-deletion Auth required

Cancel a previously scheduled account deletion (idempotent on already-active accounts)

Responses

No response body

health

get/health

Liveness probe — process is running

Responses

application/json

statusstringrequired

"ok"

timestampstringrequired

servicestringrequired

versionstringrequired

get/ready

Readiness probe — dependencies reachable

Responses

application/json

statusstringrequired

"ok""degraded"

timestampstringrequired

servicestringrequired

versionstringrequired

checksobjectrequired

dynamodbobjectrequired

okbooleanrequired