Data Models
Understand the data structures and schemas used in the Cherry.tv Affiliates API
Data Models
This page describes the data structures returned by the Cherry.tv Affiliates API.
Row
The main response object that contains all information about a model and their room.
interface Row {
model: Model; // Model information
links: Links; // Affiliate and room URLs
embed: Embed; // Embedding information
room: Room; // Current room status
}Model
Contains detailed information about a model.
interface Model {
id: string; // Unique identifier
username: string; // Unique username
name: string; // Display name
avatar: string; // URL to avatar image
age: number; // Model's age
gender: BroadcastCategory; // Gender category (0-7)
country: string | null; // Country code
level: number; // Model level
followers: number; // Number of followers
spoken_languages: string[]; // Languages the model speaks
tags: string[]; // Hashtags associated with the model
internal_tags: string[]; // Internal marketing tags
categories: string[]; // Model categories
social_links: object; // Social media links
images: object; // Additional model images
country_name: string; // Full country name
level_progress: number; // Experience bar percentage (0-100)
about: string; // Model's bio/description
location: string; // Model's location
is_new: boolean; // True if model is a newcomer
}Gender Categories (BroadcastCategory)
| Value | Description |
|---|---|
| 0 | Female |
| 1 | Male |
| 2 | Couple |
| 3 | Trans |
| 4 | Non-binary |
| 5 | Other |
| 6 | Unknown |
| 7 | All |
Links
Contains URLs for affiliate purposes.
interface Links {
affiliate_url: string; // Direct affiliate URL to model room
room_url: string; // Direct URL to model room
}Example
{
"affiliate_url": "https://cherry.tv/examplemodel?ref_affid=12345&ref_oid=tracking123",
"room_url": "https://cherry.tv/examplemodel"
}Embed
Contains URLs and information for embedding the model's room.
interface Embed {
stream_url: string; // URL for embedding the stream
room_url: object; // Room URL object
room_url_revshare: object; // Revenue sharing room URL object
}Example
{
"stream_url": "https://cherry.tv/embed/examplemodel",
"room_url": {},
"room_url_revshare": {}
}Room
Contains current room status and information.
interface Room {
status: RoomStatus; // Current room status (0-3)
thumbnail: object; // Snapshot of current stream
viewers: number; // Current viewer count
subject: object; // Room subject/topic
}Room Status Values
| Value | Status | Description |
|---|---|---|
| 0 | Offline | Model is not broadcasting |
| 1 | Online | Model is currently live |
| 2 | Private | Model is in a private show |
| 3 | Away | Model is away/idle |
Query Parameters for Filtering
When using the /affiliates/v1/models endpoint, you can filter results using these parameters:
Available Filters
| Parameter | Type | Description | Example Values |
|---|---|---|---|
| category | any | Filter by category | "masturbation" |
| username | any | Filter by specific username | "examplemodel" |
| tag | any | Filter by tag | "blonde" |
| language | any | Filter by spoken language | "english" |
| gender | number | Filter by gender (0-7) | 0 (female) |
| sort | string | Sort direction | "asc", "desc" |
| order | string | Sort field | "id", "viewer" |
| offset | any | Pagination offset | 0, 20, 40 |
| status | number | Filter by room status (0-3) | 1 (online) |
| limit | any | Number of results to return | 10, 50, 100 |
Example Filtered Request
curl "https://api.cherry.tv/affiliates/v1/models?apiKey=YOUR_API_KEY&gender=0&status=1&limit=20&sort=desc&order=viewer"This request would return the top 20 female models who are currently online, sorted by viewer count in descending order.
Error Handling
The API returns standard HTTP status codes. Common error responses include:
401 Unauthorized
{
"error": "Invalid API key",
"statusCode": 401
}404 Not Found
{
"error": "Model not found",
"statusCode": 404
}400 Bad Request
{
"error": "Invalid parameter value",
"statusCode": 400
}