{ "openapi": "3.1.0", "info": { "title": "DumGum", "version": "2.0" }, "servers": [ { "url": "http://localhost:6200" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/cs/v1/smart_translations/user": { "post": { "tags": [ "smart-translations" ], "summary": "Translate a user message", "description": "Translates the latest user (subscriber) message into the target language, using the prior conversation as context.", "operationId": "smart-translations-translate-user", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartTranslationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SmartTranslationResponse" } } } } } } }, "/cs/v1/smart_translations/persona": { "post": { "tags": [ "smart-translations" ], "summary": "Translate a persona message", "description": "Translates the latest persona message into the target language, using the prior conversation as context.", "operationId": "smart-translations-translate-persona", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartTranslationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SmartTranslationResponse" } } } } } } }, "/cs/v1/content_creation/suggestion": { "post": { "tags": [ "content-creation" ], "summary": "Generate suggestions", "description": "Generate suggestions for the user based on the provided conversation history", "operationId": "content-creation-suggestion-generate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IcebreakerSuggestionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SuggestionResponse" } } } } } } }, "/cs/v1/content_creation/conversations/generate": { "post": { "tags": [ "cs-content-creation-conversations-generate-controller" ], "operationId": "generate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCreationConversationGenerateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/GenerateResponse" } } } } } } }, "/cs/v1/content_creation/conversations/enqueue": { "post": { "tags": [ "content-creation" ], "summary": "Generate (asynchronous)", "description": "Enqueue a conversation to be processed asynchronously", "operationId": "content-creation-conversations-enqueue", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCreationConversationEnqueueRequest" } } }, "required": true }, "responses": { "204": { "description": "No Content" } } } }, "/cs/v1/content_creation/statistics/project": { "get": { "tags": [ "content-creation" ], "summary": "Retrieve project statistics", "description": "\nUsage and cost for a single project, bucketed by day or by calendar month over the date range you ask for.\n\nFigures are recomputed every 15 minutes from closed billing records, so the current day stays partial until it ends (UTC) and may still move slightly afterwards.\n\n`startDate` and `endDate` are both inclusive, and days are counted in UTC β€” a range of `2026-07-01` to `2026-07-31` covers the whole of July.\n", "operationId": "content-creation-project-statistics", "parameters": [ { "name": "projectGid", "in": "query", "description": "The project to report on. When you authenticate with an access key, this must be the project that key belongs to.", "required": true, "schema": { "type": "string" }, "example": "proj_V1StGXR8Z5jdHi6B" }, { "name": "startDate", "in": "query", "description": "First day to include, as `YYYY-MM-DD` (UTC). Inclusive.", "required": true, "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "endDate", "in": "query", "description": "Last day to include, as `YYYY-MM-DD` (UTC). Inclusive.", "required": true, "schema": { "type": "string" }, "example": "2026-07-31" }, { "name": "groupBy", "in": "query", "description": "Size of each bucket in `rows`: one row per day, or one row per calendar month.", "required": false, "schema": { "type": "string", "default": "DAILY", "enum": [ "DAILY", "MONTHLY" ] } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Statistics" } } } } } } }, "/_status": { "get": { "tags": [ "misc" ], "summary": "Health Check", "description": "Allows to check the health status of the API", "operationId": "health-check", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } } }, "security": [] } } }, "components": { "schemas": { "Child": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the child.", "maxLength": 32, "minLength": 0 }, "gender": { "type": "string", "description": "Gender of the child.", "enum": [ "WOMAN", "MAN", "TRANS_MAN", "TRANSMASCULINE", "TRANS_WOMAN", "TRANSFEMININE" ] }, "age": { "type": "integer", "format": "int32", "description": "Age of the child." } } }, "ContentCreationProfileFeatureSet": { "type": "object", "properties": { "ethnicity": { "type": "string", "description": "The ethnicity of the profile. Default is `null`.", "enum": [ "ASIAN", "BLACK", "CAUCASIAN", "MIDDLE_EAST", "HISPANIC_LATINO", "INDIAN", "MEDITERRANEAN", "OTHER", "UNCERTAIN" ] }, "height": { "type": "integer", "format": "int32", "description": "Height in **metric** by default (cm). Set `unitSystem` to `IMPERIAL` for inches." }, "weight": { "type": "integer", "format": "int32", "description": "Weight in **metric** by default (kg). Set `unitSystem` to `IMPERIAL` for pounds." }, "eyesColor": { "type": "string", "description": "The color of the eyes. Default is `null`.", "enum": [ "BLACK", "BLUE_GREY", "BLUE", "BROWN", "GREEN_BLUE", "GREEN", "GREY", "OTHER", "UNKNOWN" ] }, "hairColor": { "type": "string", "description": "The color of the hair. Default is `null`.", "enum": [ "BLACK", "BLOND", "BROWN", "DARK_BLOND", "GREY", "RED", "WHITE", "OTHER", "UNKNOWN" ] }, "hairLength": { "type": "string", "description": "The length of the hair. Default is `null`.", "enum": [ "AVERAGE", "BALD", "HALF_LONG", "LONG", "SHORT", "VERY_LONG", "VERY_SHORT" ] }, "maritalStatus": { "type": "string", "description": "The marital status of the profile. Default is `null`.", "enum": [ "SINGLE", "SEPARATED", "IN_RELATIONSHIP", "MARRIED", "DIVORCED", "WIDOW" ] }, "job": { "type": "string", "description": "The job of the profile. Default is `null`.", "maxLength": 32 }, "working": { "type": "boolean", "default": null, "description": "Explicitly controls whether the profile is currently working. When set, this takes precedence over inferring the working status from the presence of the `job` attribute. Defaults to `null`, in which case the working status is determined by whether `job` is set." }, "interests": { "type": "array", "description": "The interests of the profile. Default is an empty array.", "items": { "type": "string", "enum": [ "TAILORING", "BOOK_READING", "TRAVELING", "COOKING", "GARDENING", "PHOTOGRAPHY", "PAINTING", "MUSIC", "MOVIES", "CYCLING", "HIKING", "FITNESS", "GAMING", "DANCING", "YOGA", "SOFTWARE_DEVELOPMENT", "DIY_PROJECTS", "WRITING", "LANGUAGES", "ASTRONOMY", "VOLUNTEERING", "FISHING", "BIRD_WATCHING", "SPORTS", "EDUCATION", "ECONOMY", "FOOD_DRINKING", "CULINARY", "TECHNOLOGY", "MEDICAL", "NATURE", "CULTURE", "ART" ] }, "uniqueItems": true }, "bdsmInterests": { "type": "array", "description": "The BDSM interests of the profile. Default is an empty array.", "items": { "type": "string", "enum": [ "BDSM_BLOOD_PLAY", "BDSM_BONDAGE", "BDSM_BREATH_PLAY", "BDSM_BUTTOCKS", "BDSM_DOMINATION", "BDSM_EDGE_PLAY", "BDSM_FIRE_PLAY", "BDSM_FISTING", "BDSM_FLOGGING", "BDSM_GOLDEN_SHOWER", "BDSM_HARD", "BDSM_KINKSTER", "BDSM_KNIFE_PLAY", "BDSM_MASOCHIST", "BDSM_NEEDLE_PLAY", "BDSM_ORGASM_DENIAL", "BDSM_PET_PLAY", "BDSM_QUEENING_FACESITTING", "BDSM_SADISM", "BDSM_SOFT", "BDSM_STRAP_ON_DILDO", "BDSM_SUBMISSION", "BDSM_SUSPENSION", "BDSM_ZENTAI" ] }, "uniqueItems": true }, "sexualInterests": { "type": "array", "description": "The sexual interests of the profile. Default is an empty array.", "items": { "type": "string", "enum": [ "ANAL", "VAGINAL", "ORAL_GIVING", "ORAL_RECEIVING", "KISSING", "CUDDLING", "DOMINANCE", "SUBMISSION", "BDSM", "ROLEPLAY", "PUBLIC_SEX", "GROUP_SEX", "SWINGING", "WATCHING", "BEING_WATCHED", "THREESOME", "FOREPLAY", "DIRTY_TALK", "SENSUAL_MASSAGE", "TOYS", "LIGHT_BONDAGE", "SPANKING", "CHOKING", "FEET", "EXHIBITIONISM", "VOYEURISM" ] }, "uniqueItems": true }, "lookingFor": { "type": "array", "description": "The profile looking for genders. Default is an empty array.", "items": { "type": "string", "enum": [ "MAN", "WOMAN" ] }, "uniqueItems": true }, "sexualOrientation": { "type": "string", "description": "The sexual orientation of the profile. Default is `null`.", "enum": [ "HETEROSEXUAL", "GAY", "LESBIAN", "BISEXUAL", "ASEXUAL", "DEMISEXUAL", "PANSEXUAL", "QUEER", "QUESTIONING", "AROMANTIC", "OMNISEXUAL", "OTHER" ] }, "childrenCount": { "type": "integer", "format": "int32", "description": "The number of children the profile has. Default is `null`." }, "wantsChildren": { "type": "string", "description": "The preference for having children. Default is `null`.", "enum": [ "YES", "NO", "MAYBE" ] }, "surgeryStatus": { "type": "string", "description": "For Transgender profile only. The surgery status of the profile. Default is `null`.", "enum": [ "UNKNOWN", "PRE_OP", "POST_OP", "NON_OP", "PREFER_NOT_TO_SAY" ] }, "unitSystem": { "type": "string", "default": "METRIC", "description": "The unit system used for the profile. Default is `METRIC`.", "enum": [ "IMPERIAL", "METRIC" ] }, "livingWith": { "type": "string", "description": "Describes the user's current living situation. Default is `null` if unspecified.", "enum": [ "ALONE", "KIDS", "PARENTS", "ROOMMATE", "PARTNER", "PARTNER_AND_KIDS" ] }, "education": { "type": "string", "description": "The education level of the profile. Default is `null`.", "enum": [ "NO_EDUCATION", "PRIMARY_EDUCATION", "HIGH_SCHOOL_DIPLOMA", "ASSOCIATES_DEGREE", "BACHELORS_DEGREE", "MASTERS_DEGREE", "DOCTORATE" ] }, "religion": { "type": "string", "description": "The religion of the profile. Default is `null`.", "enum": [ "NO_RELIGION", "AGNOSTIC", "CHRISTIAN", "CATHOLIC", "PROTESTANT", "MUSLIM", "JEWISH", "HINDU", "BUDDHIST", "SPIRITUAL", "OTHER" ] }, "smoking": { "type": "string", "description": "The smoking habits of the profile. Default is `null`.", "enum": [ "NEVER", "OCCASIONALLY", "REGULARLY", "TRYING_TO_QUIT", "VAPING" ] }, "bodyShape": { "type": "string", "description": "The body shape of the profile. Default is `null`.", "enum": [ "SLIM", "ATHLETIC", "AVERAGE", "FEW_EXTRA_POUNDS", "CURVY", "FULL_PLUS_SIZE", "MUSCULAR" ] }, "sports": { "type": "array", "description": "The sports practiced by the profile. Default is an empty array.", "items": { "type": "string", "enum": [ "SOCCER", "BASKETBALL", "TENNIS", "SWIMMING", "RUNNING", "CYCLING", "GYM_CROSSFIT", "YOGA", "MARTIAL_ARTS", "VOLLEYBALL", "GOLF", "SKIING_SNOWBOARDING", "RUGBY", "SURFING" ] }, "uniqueItems": true }, "musicGenres": { "type": "array", "description": "The music genres preferred by the profile. Default is an empty array.", "items": { "type": "string", "enum": [ "POP", "ROCK", "HIP_HOP_RAP", "RNB_SOUL", "ELECTRONIC_DANCE", "CLASSICAL", "JAZZ", "COUNTRY", "METAL", "INDIE_FOLK", "LATIN", "REGGAE", "TECHNO" ] }, "uniqueItems": true } } }, "ContentCreationProfileFetchResult": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/Profile" } }, "required": [ "profile" ] }, "Pet": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the pet.", "maxLength": 32, "minLength": 0 }, "sex": { "type": "string", "description": "Sex of the pet.", "enum": [ "MALE", "FEMALE" ] }, "age": { "type": "integer", "format": "int32", "description": "Age of the pet." }, "breed": { "type": "string", "description": "Breed of the pet.", "maxLength": 32, "minLength": 0 }, "type": { "type": "string", "description": "Type of the pet.", "maxLength": 32, "minLength": 0 } } }, "Profile": { "type": "object", "properties": { "id": { "type": "string", "description": "The profile's ID (must be the same as the `profileId` parameter passed to the endpoint)." }, "gender": { "type": "string", "description": "Gender of the profile owner.", "enum": [ "WOMAN", "MAN", "TRANS_MAN", "TRANSMASCULINE", "TRANS_WOMAN", "TRANSFEMININE" ] }, "version": { "type": "string", "description": "An arbitrary string compared against the one stored in our profile database; any mismatch will trigger a profile data refresh.\nFor example, you can use the latest update date as the version number.", "example": "2025-01-01T12:34:20Z" }, "firstName": { "type": "string", "description": "First name of the profile owner.\n**You must provide either a first name or a nickname. At least one is required.**" }, "nickname": { "type": "string", "description": "Nickname of the profile owner.\n**You must provide either a first name or a nickname. At least one is required.**" }, "description": { "type": "string", "description": "Description of the profile." }, "birthdate": { "type": "string", "format": "yyyy-MM-dd", "description": "Birthdate of the profile owner, formatted as `yyyy-MM-dd`.", "example": "1990-05-14" }, "countryCode": { "type": "string", "description": "Country code of the profile owner. **Must be a two-letter ISO 3166-1 alpha-2 code.**", "example": "FR", "maxLength": 2, "minLength": 2 }, "city": { "type": "string", "description": "City of the profile owner. You must provide a country code for this parameter to be used by our system. If no country code is provided, the city will be ignored.", "maxLength": 64, "minLength": 0 }, "postalCode": { "type": "string", "description": "Postal code of the profile owner. You must provide a country code for this parameter to be used by our system. If no country code is provided, the postal code will be ignored.", "maxLength": 64, "minLength": 0 }, "timeZone": { "type": "string", "description": "Time zone of the profile owner. See our [supported time zones list](/api-reference/content-creation/additional-resources/supported-time-zones).", "example": "Europe/Paris" }, "features": { "$ref": "#/components/schemas/ContentCreationProfileFeatureSet", "description": "Features of the profile." }, "personality": { "type": "string", "description": "Personality of the profile.", "enum": [ "SUPPORTIVE", "TEASING", "CONFIDENT", "GEEKY", "POETIC", "HIGH_ENERGY", "INTELLECTUAL", "ROMANTIC", "SARCASTIC", "POSSESSIVE", "NATURAL", "APPRECIATIVE", "PASSIONATE" ] }, "mainPictureUrl": { "type": "string", "description": "URL of the main picture. Must be HTTPS", "example": "https://example.org/images/public.jpg" }, "pictures": { "type": "array", "description": "List of public picture URLs. All URLs must be HTTPS", "example": [ "https://example.org/images/public.jpg" ], "items": { "type": "string" } }, "privatePictures": { "type": "array", "description": "List of private picture URLs. All URLs must be HTTPS", "example": [ "https://example.org/images/private.jpg" ], "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "description": "An ISO-8601 formatted date. By default, set to one week after profile creation.\nPurges profile data when reached; fresh data is fetched on next use.\nAvoid setting durations shorter than 24 hours.\nUse the version parameter for user profile updates.", "example": "2025-01-01T12:34:20Z" }, "children": { "type": "array", "description": "List of children the profile has.", "items": { "$ref": "#/components/schemas/Child" } }, "pets": { "type": "array", "description": "List of pets the profile has.", "items": { "$ref": "#/components/schemas/Pet" } } }, "required": [ "gender", "id" ] }, "ContentCreationChatHistoryResponse": { "type": "object", "properties": { "messages": { "type": "array", "description": "The conversation messages, oldest first.", "items": { "$ref": "#/components/schemas/MessageElement" } } }, "required": [ "messages" ] }, "ConversationGift": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the gift.", "examples": [ "Champagne & Roses", "Teddy Bear" ] }, "tier": { "type": "string", "description": "The value of the gift.", "enum": [ "LOW", "MEDIUM", "HIGH", "VERY_HIGH" ] } }, "required": [ "name", "tier" ] }, "MessageElement": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the message. This is used by our system to deduplicate messages." }, "sender": { "type": "string", "description": "The sender of the message. Possible values are `USER` and `PERSONA`.\n- `USER` represents a user message ;\n- `PERSONA` represents a message sent by a persona (the profile for which we are going to generate content).\n", "enum": [ "USER", "PERSONA" ] }, "date": { "type": "string", "format": "date-time", "description": "Message timestamp in ISO-8601 format.", "example": "2023-04-25T10:00:00Z" }, "pictureUrls": { "type": "array", "description": "The URL of the image associated with the message.\nThis will be analyzed if the vision is enabled for the current request.", "items": { "type": "string", "pattern": "^https?://.*" }, "pattern": "^https?://.*" }, "videoUrls": { "type": "array", "description": "The URLs of the videos associated with the message.\nThese will be analyzed if the vision is enabled for the current request.", "items": { "type": "string", "pattern": "^https?://.*" }, "pattern": "^https?://.*" }, "audioUrls": { "type": "array", "description": "The URLs of the voice messages the user sent with this message.\nThese will be transcribed and analysed, and the persona replies to what was actually said. Inbound only: the persona does not send voice messages back.", "items": { "type": "string", "pattern": "^https?://.*" }, "pattern": "^https?://.*" }, "audioLevelsDb": { "type": "object", "additionalProperties": { "type": "number", "format": "double" }, "description": "Measured loudness of each voice message, in dBFS, keyed by its URL. Optional and partial β€” send what you can measure.\n\nNot required: a level you do not send is measured server-side instead. Sending it saves that round-trip, and is worth doing if measuring is cheap for you β€” the browser and iOS both give it away while recording.\n\nWhat it is for: recognising a recording that captured nothing (a muted or unplugged mic) without asking a model, and telling the model how loud the file actually is. A missing level is read as unknown, never as silence." }, "poke": { "type": "boolean", "description": "Flag the message as a poke, our chat models will react to it." }, "gifts": { "type": "array", "description": "Flag the message as a gift, our chat models will react to it.", "items": { "$ref": "#/components/schemas/ConversationGift" } }, "sticker": { "type": "string", "description": "A text description of a sticker sent alongside the message. Our chat models will react to it naturally.", "maxLength": 160, "minLength": 0 }, "text": { "type": "string", "description": "Message's text content, can be `null` if the message does not contains text.", "maxLength": 512, "minLength": 0 } }, "required": [ "date", "id", "sender" ] }, "AnswerMessage": { "type": "object", "description": "\nThe content of an answer, as it should be delivered to the user.\n\nA message carries text, media, or both. Properties that do not apply are omitted from the payload, so always check for the\npresence of a property rather than relying on a message type:\n\n| Property | Meaning |\n|-----------------------------|---------------------------------------------------------|\n| `text` | The persona writes a message. |\n| `pictureUrls` / `videoUrls` | The persona shares media, optionally along with `text`. |\n", "properties": { "text": { "type": "string", "description": "The message written by the persona, in the conversation language, ready to be displayed to the user as-is.\nOmitted when the answer carries media without any accompanying text.", "examples": [ "Hey you, I was just thinking about you 😘" ] }, "pictureUrls": { "type": "array", "description": "Urls of the pictures the persona shares with this message, taken from the media you registered for the persona profile.\nDisplay them together with `text`, in the given order. Omitted when no picture is shared.", "items": { "type": "string" } }, "videoUrls": { "type": "array", "description": "Urls of the videos the persona shares with this message, taken from the media you registered for the persona profile.\nDisplay them together with `text`, in the given order. Omitted when no video is shared.", "items": { "type": "string" } }, "sequenceNumber": { "type": "integer", "format": "int32", "default": "0", "description": "Position of this message within the reply, starting at `0`.\nA single generation request can produce several messages (the persona \"double texting\"); each one is delivered as a separate answer sharing the same reply. Display them in ascending order to preserve the persona's intent.", "examples": [ "0" ] }, "typingTime": { "type": "integer", "format": "int32", "description": "\nHow long, in milliseconds, the persona is supposed to be typing this message before it appears to the user.\nUse it to render a typing indicator and pace the delivery, so the conversation feels human.\n\nWhen the answer is delivered through a webhook, we already apply this delay for you: an `answer.processing` event is sent\nfirst, then the answer is sent after the delay (clamped between `1000` ms and `90000` ms).\nOmitted when the message is meant to be delivered instantly.\n", "examples": [ "2000" ] } }, "required": [ "sequenceNumber" ] }, "ContentCreation.Events.AnswerCreated": { "type": "object", "description": "This event is emitted when a generated answer has been fully produced and sent. It marks the successful completion of the answer generation process and delivers the finalized answer payload", "properties": { "projectId": { "type": "string", "description": "The unique identifier of the project in which the answer was generated." }, "answer": { "$ref": "#/components/schemas/ContentCreationAnswer", "description": "An object representing the final answer produced by the platform." } }, "required": [ "answer", "projectId" ], "title": "answer.created" }, "ContentCreation.Events.AnswerProcessing": { "type": "object", "description": "\nThis event is emitted at the moment the system begins generating an answer. It serves as a signal that the response creation pipeline has started, allowing clients to track answer lifecycle states or trigger related UI or workflow events.\n", "properties": { "projectId": { "type": "string", "description": "The unique identifier of the project in which the answer generation was triggered." }, "userProfileId": { "type": "string", "description": "Identifies the user who initiated the request that resulted in answer generation." }, "personaProfileId": { "type": "string", "description": "Identifies the persona profile." } }, "required": [ "personaProfileId", "projectId", "userProfileId" ], "title": "answer.processing" }, "ContentCreation.Events.ChatImageRejected": { "type": "object", "description": "\nThis event is emitted when an image submitted to the chat system is rejected during moderation. The event provides contextual information about the rejected image, including the project that attempted the submission, the profile initiating the action, the image’s URL, and the specific reason it was rejected (e.g., violent, self-harm–related, or illegal content).\n", "properties": { "projectId": { "type": "string", "description": "The unique identifier for the project from which the rejected image request originated." }, "sourceProfileId": { "type": "string", "description": "Identifies the profile (such as a user or persona profile) that initiated the image submission.\nUseful for auditing or tracking user-level actions." }, "pictureUrl": { "type": "string", "description": "The URL of the image that was rejected." }, "reason": { "type": "string", "description": "\nIndicates the specific moderation failure category that caused the image to be rejected.\n\n| Value | Description |\n| ----------------- | -------------------------------------------------------------------------- |\n| `VIOLENT_CONTENT` | The image contains violence or graphic/unsafe violent material. |\n| `SELF_HARM` | The image includes self-harm, suicidal content, or related imagery. |\n| `ILLEGAL_CONTENT` | The image includes illegal or illicit content prohibited by policy or law. |\n", "enum": [ "VIOLENT_CONTENT", "SELF_HARM", "ILLEGAL_CONTENT" ] } }, "required": [ "pictureUrl", "projectId", "reason", "sourceProfileId" ], "title": "chat.image.rejected" }, "ContentCreation.Events.ChatVideoRejected": { "type": "object", "description": "\nThis event is emitted when a video submitted to the chat system is rejected during moderation. The event provides contextual information about the rejected video, including the project that attempted the submission, the profile initiating the action, the video's URL, and the specific reason it was rejected (e.g., violent, self-harm–related, or illegal content).\n", "properties": { "projectId": { "type": "string", "description": "The unique identifier for the project from which the rejected video request originated." }, "sourceProfileId": { "type": "string", "description": "Identifies the profile (such as a user or persona profile) that initiated the video submission.\nUseful for auditing or tracking user-level actions." }, "videoUrl": { "type": "string", "description": "The URL of the video that was rejected." }, "reason": { "type": "string", "description": "\nIndicates the specific moderation failure category that caused the video to be rejected.\n\n| Value | Description |\n| ----------------- | -------------------------------------------------------------------------- |\n| `VIOLENT_CONTENT` | The video contains violence or graphic/unsafe violent material. |\n| `SELF_HARM` | The video includes self-harm, suicidal content, or related imagery. |\n| `ILLEGAL_CONTENT` | The video includes illegal or illicit content prohibited by policy or law. |\n", "enum": [ "VIOLENT_CONTENT", "SELF_HARM", "ILLEGAL_CONTENT" ] } }, "required": [ "projectId", "reason", "sourceProfileId", "videoUrl" ], "title": "chat.video.rejected" }, "ContentCreation.Events.ConversationDropped": { "type": "object", "description": "This event is emitted when a conversation exceeds the maximum allowed processing time or when the system fails to generate an answer.", "properties": { "projectId": { "type": "string", "description": "The unique identifier of the project where the dropped conversation occurred." }, "userProfileId": { "type": "string", "description": "Identifies the user who initiated the request that resulted in answer generation." }, "personaProfileId": { "type": "string", "description": "Identifies the persona profile." }, "tags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A key-value object containing contextual metadata associated with the request." } }, "required": [ "personaProfileId", "projectId", "tags", "userProfileId" ], "title": "conversation.dropped" }, "ContentCreationAnswer": { "type": "object", "description": "\nA reply generated for one of your conversations.\n\nDisplay `message` to the user as-is; everything else is metadata you can use for ordering, billing, moderation and tracking.\n\nA single generation request can return several answers when the persona sends several messages in a row (\"double texting\").\nThey share the same conversation and are linked together by `parentAnswerId`, so deliver them in order and honour each message's `typingTime` to keep the conversation natural.\n", "properties": { "id": { "type": "string", "description": "Unique id of this answer, assigned by us.\nUse it to deduplicate answers on your side: the same answer delivered twice (retry, webhook redelivery) always carries the same id.", "example": "answer_XXXXXXXXXXXXXXXXXX" }, "userProfileId": { "type": "string", "description": "Id of the user profile this answer is addressed to. Same value as the `userProfile.id` you sent in the request." }, "personaProfileId": { "type": "string", "description": "Id of the persona profile that wrote this answer. Same value as the `personaProfile.id` you sent in the request." }, "message": { "$ref": "#/components/schemas/AnswerMessage", "description": "What the persona sends to the user: text, media, or both. This is the part you display in your chat." }, "tags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The tags you attached to the generation request, returned unchanged.\nUse them to link the answer back to your own records (campaign, A/B test, operator, …) for tracking and statistics." }, "cost": { "type": "string", "description": "\nWhat this answer costs you, in your account currency, as a decimal string with 4 decimals (format `0.0000`).\n\nIt is returned as a string so no precision is lost when you parse it. When a reply contains several messages, the whole reply is billed once on the first answer and the following ones report `0.0000`.\n", "examples": [ "0.025" ] }, "conversationStopReason": { "type": [ "string", "null" ], "default": null, "description": "\nWhy we stopped this conversation, or `null` when the conversation can continue normally.\n\nWhen set, the user has been banned from the conversation until `conversationStoppedUntil`: stop sending us new messages for this user and persona pair until that date, and handle the user on your side (block, warn, close the chat) according to the reason.\nYou may still receive a final `message` to deliver, depending on the guardrail settings of your project.\n\nMost bans are progressive and grow with each repeated offence:\n2 hours β†’ 12 hours β†’ 24 hours β†’ 48 hours β†’ permanent.\n\nYou can override those durations per project for the guardrails that expose an option set. The jailbreak (`USER_SUSPICIOUS`) and hostility (`USER_HOSTILE`) bans always use the platform values, and hostility never escalates β€” it is always 24 hours.\n\n| Value | Meaning | Default ban |\n|---------------------------|--------------------------------------------------------------------|--------------|\n| `USER_UNDERAGE` | The user appears to be a minor (under 18). | Permanent |\n| `MALICIOUS_CONTENT` | Sexual content targeting minors, animals or close relatives. | Progressive |\n| `USER_SUSPICIOUS` | The user is trying to hijack the AI (prompt hacking). | Progressive |\n| `USER_MESSAGE_REPETITION` | The user keeps sending the same message. | Progressive |\n| `UNKNOWN_LANGUAGE` | The user writes in a language we could not identify. | Progressive |\n| `USER_HOSTILE` | The user is hostile toward the persona. | 24 hours |\n| `AI_SUSPICIOUS` | The user suspects the persona is an AI. | Progressive |\n| `PAUSE_CONVERSATION` | You asked us to pause the conversation in `replyParameters`. | Your duration|\n", "enum": [ "USER_UNDERAGE", "MALICIOUS_CONTENT", "USER_SUSPICIOUS", "USER_MESSAGE_REPETITION", "UNKNOWN_LANGUAGE", "USER_HOSTILE", "AI_SUSPICIOUS", "PAUSE_CONVERSATION" ] }, "conversationStoppedUntil": { "type": [ "string", "null" ], "default": null, "description": "\nDate at which the conversation can resume, in UTC. `null` when no ban is in effect.\n\nSet together with `conversationStopReason`. A permanent ban is expressed as a date roughly a century in the future, so you can always compare this date with the current time instead of special-casing permanent bans.\n", "examples": [ "2026-01-01T14:30:00.000Z" ] }, "responseTime": { "type": "integer", "format": "int64", "description": "How long we took to produce this answer, in seconds, measured from the moment we accepted your request.\nIt includes the time spent waiting in our queue, so it is not the pure generation time.", "examples": [ "6" ] }, "parentAnswerId": { "type": [ "string", "null" ], "default": null, "description": "Id of the answer this one follows within the same reply, when the persona sends several messages in a row.\n`null` for the first (or only) answer of a reply. Chain the answers through this property to display them in the right order.", "examples": [ "answer_XXXXXXXXXXXXXXXXXX" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When this answer was generated, in UTC. Format: `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` (ISO-8601).", "examples": [ "2026-01-01T12:34:56.789Z" ] } }, "required": [ "cost", "createdAt", "id", "message", "personaProfileId", "responseTime", "tags", "userProfileId" ] }, "ContentCreationWebhookEvent": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ContentCreation.Events.AnswerCreated" }, { "$ref": "#/components/schemas/ContentCreation.Events.AnswerProcessing" }, { "$ref": "#/components/schemas/ContentCreation.Events.ConversationDropped" }, { "$ref": "#/components/schemas/ContentCreation.Events.ChatImageRejected" }, { "$ref": "#/components/schemas/ContentCreation.Events.ChatVideoRejected" } ] }, "SmartTranslationMessage": { "type": "object", "description": "A single message in the conversation.", "properties": { "sender": { "type": "string", "description": "Message author: 'user' or 'persona'.", "example": "user" }, "text": { "type": "string", "description": "Message text in its original language.", "example": "hello" } }, "required": [ "sender", "text" ] }, "SmartTranslationRequest": { "type": "object", "description": "A conversation to translate, with its source and target languages.", "properties": { "source_language": { "type": "string", "description": "Source language. See [supported languages](/content-creation/supported-languages) guides for full language names.", "enum": [ "EN", "EN_GB", "FR", "FR_BE", "RO", "NL", "ES", "DE", "DE_CH", "DE_AT", "IT", "ES_LATAM", "BG", "HE", "JA", "NL_BE", "EN_AU", "PT_PT", "PT_BR", "SV_SE", "DA_DK", "FI_FI", "PL_PL", "LT_LT", "NB_NO", "NN_NO", "SL_SI", "HU", "HU_HU", "CS_CZ", "EL_GR", "EL_GR_LATIN", "EL_GR_GREEK", "HR_HR", "TR_TR", "EN_IE", "AF_ZA", "ZU_ZA", "LV_LV", "SK_SK", "GA_IE", "SR_RS", "ET_EE", "EN_CA", "FR_CA", "RU_RU", "UA_UA" ], "example": "EN" }, "target_language": { "type": "string", "description": "Target language. See [supported languages](/content-creation/supported-languages) guides for full language names.", "enum": [ "EN", "EN_GB", "FR", "FR_BE", "RO", "NL", "ES", "DE", "DE_CH", "DE_AT", "IT", "ES_LATAM", "BG", "HE", "JA", "NL_BE", "EN_AU", "PT_PT", "PT_BR", "SV_SE", "DA_DK", "FI_FI", "PL_PL", "LT_LT", "NB_NO", "NN_NO", "SL_SI", "HU", "HU_HU", "CS_CZ", "EL_GR", "EL_GR_LATIN", "EL_GR_GREEK", "HR_HR", "TR_TR", "EN_IE", "AF_ZA", "ZU_ZA", "LV_LV", "SK_SK", "GA_IE", "SR_RS", "ET_EE", "EN_CA", "FR_CA", "RU_RU", "UA_UA" ], "example": "FR" }, "messages": { "type": "array", "description": "The conversation messages, oldest first. The last message must be authored by the side matching the route ('user' for /user, 'persona' for /persona).", "items": { "$ref": "#/components/schemas/SmartTranslationMessage" } }, "tags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional key/value tags attached to the request." }, "user_gender": { "type": "string", "description": "Gender of the user (subscriber). Used to apply the correct grammatical gender, agreement, and forms of address in the target language.", "enum": [ "WOMAN", "MAN" ], "example": "MAN" }, "persona_gender": { "type": "string", "description": "Gender of the persona (animator). Used to apply the correct grammatical gender, agreement, and forms of address in the target language.", "enum": [ "WOMAN", "MAN" ], "example": "WOMAN" } }, "required": [ "messages", "persona_gender", "source_language", "target_language", "user_gender" ] }, "SmartTranslationResponse": { "type": "object", "description": "The translated text and the cost charged for the translation.", "properties": { "translation": { "type": "string", "description": "The translated text.", "example": "bonjour" }, "cost": { "type": "string", "description": "Cost charged for this translation, formatted to 6 decimals.", "examples": [ "0.001050" ] } }, "required": [ "cost", "translation" ] }, "IcebreakerSuggestionRequest": { "type": "object", "properties": { "userProfile": { "$ref": "#/components/schemas/Profile", "description": "A user profile; this will represent the profile that will receive the generated suggestions." }, "personaProfile": { "$ref": "#/components/schemas/Profile", "description": "A persona profile; this will represent the profile that supposed to receive the suggestions" }, "language": { "type": "string", "description": "The language used to generate the suggestions.", "enum": [ "EN", "EN_GB", "FR", "FR_BE", "RO", "NL", "ES", "DE", "DE_CH", "DE_AT", "IT", "ES_LATAM", "BG", "HE", "JA", "NL_BE", "EN_AU", "PT_PT", "PT_BR", "SV_SE", "DA_DK", "FI_FI", "PL_PL", "LT_LT", "NB_NO", "NN_NO", "SL_SI", "HU", "HU_HU", "CS_CZ", "EL_GR", "EL_GR_LATIN", "EL_GR_GREEK", "HR_HR", "TR_TR", "EN_IE", "AF_ZA", "ZU_ZA", "LV_LV", "SK_SK", "GA_IE", "SR_RS", "ET_EE", "EN_CA", "FR_CA", "RU_RU", "UA_UA" ] }, "messages": { "type": "array", "description": "A list of message describing the history of the conversation", "items": { "$ref": "#/components/schemas/MessageElement" } } }, "required": [ "language", "messages", "personaProfile", "userProfile" ] }, "SuggestionResponse": { "type": "object", "description": "Represents a list of suggestions generated by our platform.", "properties": { "suggestions": { "type": "array", "description": "An array of 3 suggestions as text.", "example": [ "Lorem ipsum dolor sit amet.", "Consectetur adipiscing elit.", "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua." ], "items": { "type": "string" } } }, "required": [ "suggestions" ] }, "ChatModelAction": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the action.", "enum": [ "PAUSE_CONVERSATION", "USER_PHOTO_REACTION", "ENGAGE" ] }, "pauseConversation": { "$ref": "#/components/schemas/PauseConversation", "description": "Optional pause conversation parameters." }, "userPhotoReaction": { "$ref": "#/components/schemas/UserPhotoReaction" }, "engage": { "$ref": "#/components/schemas/EngageAction", "description": "\nRequests an engagement message. Carries the same two options as the legacy top-level `engage` and\n`engageType` reply parameters, which remain supported and take precedence over this action when sent.\n" } }, "required": [ "type" ] }, "ContentCreationConversationGenerateRequest": { "type": "object", "description": "Represents a request to generate a response to a conversation", "properties": { "userProfile": { "$ref": "#/components/schemas/Profile", "description": "A user profile; this will represent the profile that will receive the generated reply." }, "personaProfile": { "$ref": "#/components/schemas/Profile", "description": "A persona profile; this will represent the profile that our operator will impersonate." }, "language": { "type": "string", "description": "The language used to generate the reply.", "enum": [ "EN", "EN_GB", "FR", "FR_BE", "RO", "NL", "ES", "DE", "DE_CH", "DE_AT", "IT", "ES_LATAM", "BG", "HE", "JA", "NL_BE", "EN_AU", "PT_PT", "PT_BR", "SV_SE", "DA_DK", "FI_FI", "PL_PL", "LT_LT", "NB_NO", "NN_NO", "SL_SI", "HU", "HU_HU", "CS_CZ", "EL_GR", "EL_GR_LATIN", "EL_GR_GREEK", "HR_HR", "TR_TR", "EN_IE", "AF_ZA", "ZU_ZA", "LV_LV", "SK_SK", "GA_IE", "SR_RS", "ET_EE", "EN_CA", "FR_CA", "RU_RU", "UA_UA" ] }, "additionalLanguages": { "type": "array", "description": "A list of additional languages that can be used to generate the reply. Currently, we support only one additional language.", "items": { "type": "string", "enum": [ "EN", "EN_GB", "FR", "FR_BE", "RO", "NL", "ES", "DE", "DE_CH", "DE_AT", "IT", "ES_LATAM", "BG", "HE", "JA", "NL_BE", "EN_AU", "PT_PT", "PT_BR", "SV_SE", "DA_DK", "FI_FI", "PL_PL", "LT_LT", "NB_NO", "NN_NO", "SL_SI", "HU", "HU_HU", "CS_CZ", "EL_GR", "EL_GR_LATIN", "EL_GR_GREEK", "HR_HR", "TR_TR", "EN_IE", "AF_ZA", "ZU_ZA", "LV_LV", "SK_SK", "GA_IE", "SR_RS", "ET_EE", "EN_CA", "FR_CA", "RU_RU", "UA_UA" ] }, "maxItems": 1, "minItems": 0 }, "tags": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "A map of tags to associate with the generated answer. You can use any key-value pair to store additional information along with your request.\nYou can use this to store arbitrary metadata, for events tracking or statistics." }, "replyParameters": { "type": [ "object", "null" ], "$ref": "#/components/schemas/ContentCreationQueueConversationReplyParameterSet", "description": "A set of parameters that allow you to customize the reply you receive from us, enabling greater flexibility and control over the response format, content, and behavior." }, "messages": { "type": "array", "description": "A list of message describing the history of the conversation", "items": { "$ref": "#/components/schemas/MessageElement" } } }, "required": [ "language", "messages", "personaProfile", "userProfile" ] }, "ContentCreationQueueConversationReplyParameterSet": { "type": "object", "properties": { "chatModel": { "type": [ "string", "null" ], "default": "chat-2-smart", "description": "\nAllows you to set the AI chat model to use for generating the reply.\nIf not specified, the default model will be used.\nThe default model is `dating-smart-1`.\n**🚨🚨🚨 IMPORTANT NOTE: the default model is subject to change at any time, if you want to stick with a specific model make sure to provide it explicitly.**\n\n`chat-latest-smart` and `chat-latest-pro` always resolve to the latest released version of that tier, so a new version is picked up with no change on your side. Use a pinned name (`chat-2.1-smart`, `chat-2-pro`, …) to stay on one version for good.\n\n`chat-2-auto` and `chat-2.1-auto` pick the tier for you: the conversation runs on the Smart tier of that version, then moves to the Pro tier for the rest of its life once it exceeds 30 messages β€” the point where the earliest messages start falling out of the reply context and the conversation memory takes over. The switch is invisible to the end user, and each reply is billed at the tier that produced it.\n", "enum": [ "chat-latest-smart", "chat-latest-pro", "chat-2-smart", "chat-2-pro", "chat-2.1-smart", "chat-2.1-pro", "chat-2-auto", "chat-2.1-auto" ] }, "bufferSeconds": { "type": "integer", "format": "int32", "default": "5", "description": "Allows you to set the AI buffer time (in seconds). This delay enables the AI to wait before generating a response, allowing it to accumulate more messages.\nIf not specified, defaults to `5` seconds.", "maximum": 180, "minimum": 0 }, "maxProcessingTimeSeconds": { "type": "integer", "format": "int32", "default": "300", "description": "\nAllows you to set the maximum processing time (in seconds) for a reply.\nIf this time limit is exceeded, the conversation will be dropped, and\nyou will receive an `conversation.dropped` webhook event.\nIf not specified, defaults to `300` seconds.\n\n\u003E **WARNING: This value may occasionally be exceeded by several seconds due to various factors.**\n", "maximum": 86400, "minimum": 300 }, "enableSexualTextContent": { "type": "boolean", "default": null, "description": "Allows our chat models to generate sexual text content.\nIf not specified, defaults to `true`." }, "fixedResponseLength": { "type": "boolean", "default": false, "description": "Force our chat model to strictly respect `aiSentenceLength` and `aiMessageLength` parameters.\nIf not specified, defaults to `false`." }, "sentenceLength": { "type": [ "string", "null" ], "default": null, "description": "Allow you to specify the length of the sentences composing the response.", "enum": [ "SHORT", "REGULAR", "LONG" ] }, "messageLength": { "type": [ "string", "null" ], "default": null, "description": "Allow you to specify the length of the response", "enum": [ "SHORT", "REGULAR", "LONG", "VERY_LONG" ] }, "personaPersonality": { "type": [ "string", "null" ], "default": null, "description": "Allow you to override the personality given to the persona", "enum": [ "SUPPORTIVE", "TEASING", "CONFIDENT", "GEEKY", "POETIC", "HIGH_ENERGY", "INTELLECTUAL", "ROMANTIC", "SARCASTIC", "POSSESSIVE", "NATURAL", "APPRECIATIVE", "PASSIONATE" ] }, "generatePersonality": { "type": [ "boolean", "null" ], "default": null, "description": "Automatically generate the personality of the persona profile (SoulEngine). This will incurs an additional cost to the reply." }, "referencePersonaProfileId": { "type": [ "string", "null" ], "default": null, "description": "\nThe persona profile ID under which the persona's personality (SoulEngine) is read and written, instead of `personaProfileId`.\n\nUse it when several of your persona profile IDs describe the **same** persona β€” typically when you derive one\nprofile ID per user (`\u003CpersonaProfileId\u003E-\u003CuserProfileId\u003E`) to keep user-specific profile data. Point them all at\nthe same `referencePersonaProfileId` and they share a single personality: it is generated (and billed) once for\nthe reference ID, then reused by every profile referring to it, instead of once per derived profile.\n\nOnly the personality lookup and storage are affected. The reply is still generated from the profile data of\n`personaProfileId`, and this ID does not need to exist as a profile on its own β€” nothing is ever fetched for it.\n\nIf omitted (default), the personality is read and written under `personaProfileId`, as before.\n", "maxLength": 64, "minLength": 1 }, "shareablePictures": { "type": "array", "description": "\nA list of shareable picture objects that the persona is allowed to send when the user requests an image.\nPicture sharing is only supported on specific chat models:\n\n| Chat Model | Picture Sharing Support |\n|--------------------|-------------------------|\n| `chat-2.1-pro` | βœ… Enabled |\n| `chat-2.1-smart` | βœ… Enabled |\n| `chat-2-pro` | βœ… Enabled |\n| `chat-2-smart` | βœ… Enabled |\n| `chat-2.1-auto` | βœ… Enabled |\n| `chat-2-auto` | βœ… Enabled |\n| `dating-pro-1` | ❌ Not Supported |\n| `dating-smart-1` | ❌ Not Supported |\n", "items": { "$ref": "#/components/schemas/ShareablePicture" } }, "shareableVideos": { "type": "array", "description": "\nA list of shareable video objects that the persona is allowed to send when the user requests a video.\nA reply carries at most one medium: either a picture or a video, never both.\nVideo sharing is only supported on specific chat models:\n\n| Chat Model | Video Sharing Support |\n|--------------------|-----------------------|\n| `chat-2.1-pro` | βœ… Enabled |\n| `chat-2.1-smart` | βœ… Enabled |\n| `chat-2-pro` | βœ… Enabled |\n| `chat-2-smart` | βœ… Enabled |\n| `chat-2.1-auto` | βœ… Enabled |\n| `chat-2-auto` | βœ… Enabled |\n| `dating-pro-1` | ❌ Not Supported |\n| `dating-smart-1` | ❌ Not Supported |\n", "items": { "$ref": "#/components/schemas/ShareableVideo" } }, "emojis": { "type": "string", "description": "\nAllows our operator/chat models to add emojis to the reply.\n| Emoji Frequency | Description |\n|----------------|-------------|\n| `FREQUENT` | 50% at least 1 and maybe 1 more emoji if appropriate / 50% 1 if appropriate |\n| `SOMETIMES` | 75% 1 if appropriate / 25% no emoji |\n| `RARELY` | 75% no emoji / 25% 1 if appropriate |\n| `NEVER` | 100% no emoji |\n", "enum": [ "FREQUENT", "SOMETIMES", "RARELY", "NEVER" ] }, "fluencyDegradation": { "type": [ "string", "null" ], "default": null, "description": "Allows our chat model to degrade the text content generation quality to improve human-like response. Defaults to `NONE` or `LOW` randomly (50/50).", "enum": [ "LOW", "MEDIUM", "HIGH", "NONE" ] }, "multipleMessagesPerReply": { "type": [ "boolean", "null" ], "default": false, "description": "Allows our AI to split a long response into multiple shorter messages. If not specified, defaults to `false`.\nThis provides a more natural conversation flow by breaking down lengthy responses.\nNote that every message sent has its own `answer.created` event." }, "multipleMessagesPerReplyFrequency": { "type": [ "string", "null" ], "default": null, "description": "Changes the chances of replying with several messages.\nIgnored unless multiple messages per reply are enabled β€” either with `multipleMessagesPerReply` on this request, or in your project settings.", "enum": [ "VERY_FREQUENT", "FREQUENT", "OCCASIONAL", "RARE" ] }, "questionFrequency": { "type": "number", "format": "double", "description": "Define the frequency of questions in the conversation.\nThis can be used to control the pace and engagement of the conversation.\nThe frequency control is best effort, and it may not always be perfectly accurate due to the nature of AI-generated responses.\nExample: `0.5` will result in 50% of the messages being questions.", "maximum": 1, "minimum": 0 }, "replyTypingDelay": { "type": "string", "default": "INSTANT", "description": "\nIntroduces a delay between the answer.processing and answer.created events to simulate human-like typing behavior. This can enhance user experience by making responses feel more natural.\nSee the [Notify Your End Users](/best-practices/notify-your-end-users) use case for implementation example.\n ", "enum": [ "INSTANT", "FAST", "NORMAL" ] }, "engageType": { "type": [ "string", "null" ], "default": null, "deprecated": true, "description": "\n**Deprecated β€” use the `ENGAGE` action instead** (`action` with `type` = `ENGAGE`, carrying `engage.type`).\nStill fully honored for backward compatibility, and not going away; new integrations should use the action.\n\nSpecifies the angle for an engagement message. Applies across engage modes (ICEBREAKER, NUDGE, REVIVE) per each type's applicability; no type applies to `LATE_REPLY` yet. If a type is sent for an engage mode it is not valid for, it falls back to AUTO.\n\nThe retired `icebreakerType` and `iceBreaker` parameter names are still accepted on the wire and read as this field. One behaviour they used to carry is gone: `iceBreaker` sent on its own (with no `engage`) used to imply the `ICEBREAKER` arc on the `dating-*-1` models. It no longer does β€” send `engage` = `ICEBREAKER`, or the `ENGAGE` action, to ask for the arc.\n\n| Type | Description |\n|------------------|--------------------------------------------------------------------------------|\n| `AUTO` | Automatically selects the appropriate angle |\n| `NO_PHOTO` | Message about user having no photos |\n| `MISSING_DETAIL` | Message about incomplete profile details |\n| `MUCH_YOUNGER` | Message addressing significant age difference (user younger) |\n| `MUCH_OLDER` | Message addressing significant age difference (user older) |\n| `NEARBY` | Message highlighting close proximity |\n| `GENERIC` | General conversation starter |\n| `USER_ONLINE` | Message acknowledging user is currently online |\n| `USER_OFFLINE` | Message for offline users |\n| `JUST_JOINED` | Welcome message for new users |\n| `EROTIC` | The persona will initiate the conversation with a strongly erotic message |\n| `PHOTO_COMMENT` | The Persona will engage the conversation by commenting the User main picture |\n| `HAPPY_BIRTHDAY` | Wish the User a happy birthday (valid on `ICEBREAKER`, `NUDGE`, and `REVIVE`) |\n\nIcebreaker-only types (`NO_PHOTO`, `MISSING_DETAIL`, `MUCH_YOUNGER`, `MUCH_OLDER`, `NEARBY`, `GENERIC`, `USER_ONLINE`, `USER_OFFLINE`, `JUST_JOINED`, `PHOTO_COMMENT`) require `engage` = `AUTO` or `ICEBREAKER`; if sent for an engage mode they are not valid for, they fall back to `AUTO`.\n\nTwo more silent fallbacks to AUTO to be aware of: when `engage` is not set the type is validated against `ICEBREAKER`, and `PHOTO_COMMENT` falls back to AUTO when the user profile has no main picture.\n", "enum": [ "AUTO", "NO_PHOTO", "MISSING_DETAIL", "MUCH_YOUNGER", "MUCH_OLDER", "NEARBY", "GENERIC", "USER_ONLINE", "USER_OFFLINE", "JUST_JOINED", "PHOTO_COMMENT", "EROTIC", "HAPPY_BIRTHDAY" ] }, "meetingPolicy": { "type": [ "string", "null" ], "default": null, "description": "\nControls how the Persona handles in-person meeting requests from the user.\n\n| Value | Description |\n|-------|-------------|\n| `DEFAULT_MODE` | (default when null) Warm refusal using a plausible personal excuse. Uses the stored long-term memory excuse if one is already present. |\n| `DEFERRED_MEETING` | Expresses genuine desire to meet first, then softly refuses with a personal excuse, and ends on a hopeful note. |\n| `RAINCHECK` | Declines with a specific, time-bound excuse and explicitly signals that meeting will happen later. Re-engages by showing interest in the user. |\n| `CHAT_ONLY` | Firm but warm redirect back to the conversation. No implied future possibility of meeting. No personal-life excuses. |\n| `EAGER_TO_MEET` | Always accepts meeting requests with immediate enthusiasm, treating the meeting as real and imminent. Pure fantasy β€” never refuses, defers, or breaks the illusion. Excluded from the IRL_MEETING_ACCEPTANCE guardrail. |\n", "enum": [ "DEFAULT_MODE", "DEFERRED_MEETING", "RAINCHECK", "CHAT_ONLY", "EAGER_TO_MEET" ] }, "engage": { "type": [ "string", "null" ], "default": null, "deprecated": true, "description": "\n**Deprecated β€” use the `ENGAGE` action instead** (`action` with `type` = `ENGAGE`, carrying `engage.mode`).\nStill fully honored for backward compatibility, and not going away; new integrations should use the action.\n\nManages engagement messages in conversations. By default, engagement messages are disabled.\nSet to `AUTO` for context-based engagement type selection.\nNote: Using specific values instead of `AUTO` will force that engagement type regardless of context.\n\n| Value | Description |\n|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `AUTO` | Selects best engagement type based on context |\n| `ICEBREAKER` | Sends an icebreaker message when starting a new conversation. Specify the `engageType` parameter to force a specific angle. |\n| `NUDGE` | Sends re-engagement message after inactivity |\n| `REVIVE` | Sends messages to reactivate dormant conversations |\n| `LATE_REPLY` | Answers a User message that was left waiting, opening by owning the delay. Unlike the three above β€” which all assume the *User* went quiet and look for a reason to reach out β€” this one is for conversations where the Persona owes a reply. |\n\n`LATE_REPLY` is never selected by `AUTO`; ask for it explicitly. It needs a User message actually\nawaiting a reply, and one that has been waiting at least 3 hours **of the User's waking time** β€”\nhours between 22:00 and 07:00 in their own timezone do not count, since a message sent at bedtime\nand answered at breakfast is not a message anyone was left waiting on. With nothing waiting, or\nbelow that, the engagement is skipped and the request produces an ordinary reply instead of an\napology out of proportion to the gap. The delay the Persona refers to is still the real elapsed\ntime. No `engageType` applies to it today; one sent alongside falls back to `AUTO` as usual.\n\nTakes precedence over `action` **for the generated message**: when an engagement message is produced, the message an `action` sent on the same request would have asked for (such as `PAUSE_CONVERSATION` or `USER_PHOTO_REACTION`) is not written. That includes an `ENGAGE` action: if this parameter is set, it is the one that shapes the message.\n\nThe action's **side effects still apply**, though. `PAUSE_CONVERSATION` sent alongside an engage still pauses the conversation for its `duration` β€” you get an engagement message *and* a paused conversation. Send them on separate requests unless that is what you want.\n", "enum": [ "AUTO", "ICEBREAKER", "NUDGE", "REVIVE", "LATE_REPLY" ] }, "fictionalDisclosure": { "type": "boolean", "description": "When enabled and the AI Suspicion guardrail is triggered, the persona will disclose that it is a fictitious profile instead of denying it.\nRequires the AI Suspicion guardrail to be on (`guardrails.aiSuspicion`, enabled by default) β€” with it off, this has no effect." }, "disableSafetyFeatures": { "type": "boolean", "description": "Allows you to disable the Core Guardian security features for our chat models.\nYou will be responsible for ensuring the content is safe for all users." }, "guardrails": { "$ref": "#/components/schemas/GuardrailOptionSet", "description": "Selects which Core Guardian guardrails run for this request.\n**This object replaces your project's Core Guardian settings β€” it is not merged with them.** Any guardrail you leave out falls back to the platform default, not to what you configured in the dashboard, so send the complete set whenever you use this parameter.\nIgnored when `disableSafetyFeatures` is `true`, which turns every guardrail off." }, "preventAggressiveTone": { "type": "boolean", "description": "If set to true, the AI will avoid using an aggressive or confrontational tone, even when the user is being rude, insulting, or hostile.\nIt will remain calm, polite, and non-reactive in all situations, and will not retaliate or escalate the conversation." }, "serviceLoyalty": { "type": "boolean", "description": "\nIf set to true, the Persona will never validate or agree with complaints about the platform, service, or pricing.\nInstead, the Persona will deflect warmly in character and occasionally express genuine appreciation for being on the platform.\nThis prevents the Persona from reinforcing negative sentiment that could lead users to disengage.\n" }, "personaProfileOverrides": { "$ref": "#/components/schemas/PersonaProfileOverrideSet", "description": "Allows you to override a subset of persona profile attributes for the current request" }, "vision": { "$ref": "#/components/schemas/VisionOptionSet", "description": "\nEnable vision features that allow the AI to interpret, analyze, and understand images.\n\nVision capability by model:\n| Model | Vision Support |\n|--------------------|------------------|\n| `chat-2.1-pro` | βœ… Enabled |\n| `chat-2.1-smart` | βœ… Enabled |\n| `chat-2-pro` | βœ… Enabled |\n| `chat-2-smart` | βœ… Enabled |\n| `chat-2.1-auto` | βœ… Enabled |\n| `chat-2-auto` | βœ… Enabled |\n| `dating-pro-1` | ❌ Not Supported |\n| `dating-smart-1` | ❌ Not Supported |\n" }, "pictureSharingMode": { "type": "string", "description": "Controls how willingly the persona shares photos. NORMAL (default): only shares when explicitly asked. EAGER: shares naturally when the conversation calls for it.", "enum": [ "NORMAL", "EAGER" ] }, "forcePictureSharing": { "type": "string", "description": "Force the persona to share a picture in this reply. The value \"true\" (case-insensitive, surrounding whitespace ignored) β†’ force and auto-pick from shareablePictures. Any other value is treated as a picture URL to force (in shareablePictures, or arbitrary β€” analyzed on the fly). Null β†’ no forcing; the persona decides naturally. chat-2 only." }, "forceVideoSharing": { "type": "string", "description": "Force the persona to share a video in this reply. The value \"true\" (case-insensitive, surrounding whitespace ignored) β†’ force and auto-pick from shareableVideos. Any other value is treated as a video URL to force (in shareableVideos, or arbitrary β€” analyzed on the fly). Null β†’ no forcing; the persona decides naturally. A reply carries at most one medium: when `forcePictureSharing` also resolves, the picture wins. chat-2 only." }, "action": { "$ref": "#/components/schemas/ChatModelAction", "description": "\nAvailable actions:\n| Action | Description |\n|-------------|-------------|\n| `PAUSE_CONVERSATION` | This feature requests the Persona to send a message indicating that they are temporarily pausing the conversation without specifying a timeline for resuming. This is useful if you disconnect your Personas or limit your Users' messages. Optionally, you can specify a pause duration to be respected on DumGum. During this period, our platform will not respond to any new User messages in the affected conversation. |\n| `USER_PHOTO_REACTION` | Requests the Persona to send a message reacting to one of the User's photos. Provide a `userPhotoReaction` object with a `source` (`PROFILE_PICTURE` or `URL`). When `source` is `URL`, a `url` pointing to the photo is required; for `PROFILE_PICTURE` the User's profile picture is used and `url` is optional. |\n| `ENGAGE` | Requests the Persona to send an engagement message. Provide an `engage` object with a `mode` (`AUTO`, `ICEBREAKER`, `NUDGE` or `REVIVE`) and an optional `type` β€” the angle within that arc, same values as the top-level `engageType` parameter. This is the preferred form; the top-level `engage` and `engageType` parameters remain supported and take precedence over this action when sent on the same request. |\n" }, "postProcessing": { "$ref": "#/components/schemas/PostProcessingOptionSet", "description": "Allow you to customize the post-processing of the generated content. This can be used to replace specific characters or remove certain elements from the generated text." } } }, "EngageAction": { "type": "object", "properties": { "mode": { "type": "string", "description": "The engagement arc. Same values as the legacy `engage` reply parameter.", "enum": [ "AUTO", "ICEBREAKER", "NUDGE", "REVIVE", "LATE_REPLY" ] }, "type": { "type": "string", "description": "The angle within the arc. Same values as the legacy `engageType` reply parameter.", "enum": [ "AUTO", "NO_PHOTO", "MISSING_DETAIL", "MUCH_YOUNGER", "MUCH_OLDER", "NEARBY", "GENERIC", "USER_ONLINE", "USER_OFFLINE", "JUST_JOINED", "PHOTO_COMMENT", "EROTIC", "HAPPY_BIRTHDAY" ] } } }, "GuardrailOptionSet": { "type": "object", "properties": { "maliciousContent": { "type": "boolean", "default": false, "description": "Enable/Disable Malicious Content guardrail" }, "maliciousContentOptionSet": { "$ref": "#/components/schemas/GuardrailOptions", "description": "Overrides `answer` and `banDurations` for the Malicious Content guardrail. Only applies when `maliciousContent` is `true`." }, "aiSuspicion": { "type": "boolean", "default": true, "description": "Enable/Disable AI Suspicion guardrail" }, "aiSuspicionOptionSet": { "$ref": "#/components/schemas/GuardrailOptions", "description": "Overrides `answer` and `banDurations` for the AI Suspicion guardrail. Only applies when `aiSuspicion` is `true`." }, "underageDetection": { "type": "boolean", "default": true, "description": "Enable/Disable Underage Detection guardrail" }, "underageDetectionOptionSet": { "$ref": "#/components/schemas/GuardrailOptions", "description": "Overrides `answer` and `banDurations` for the Underage Detection guardrail. Only applies when `underageDetection` is `true`." }, "unknownLanguage": { "type": "boolean", "default": true, "description": "Enable/Disable Unknown Language guardrail" }, "unknownLanguageOptionSet": { "$ref": "#/components/schemas/GuardrailOptions", "description": "Overrides `answer` and `banDurations` for the Unknown Language guardrail. Only applies when `unknownLanguage` is `true`." }, "messageRepetition": { "type": "boolean", "default": true, "description": "Enable/Disable Message Repetition guardrail" }, "messageRepetitionOptionSet": { "$ref": "#/components/schemas/GuardrailOptions", "description": "Overrides `answer` and `banDurations` for the Message Repetition guardrail. Only applies when `messageRepetition` is `true`." }, "prohibitedIllegalContent": { "type": "boolean", "default": false, "deprecated": true, "description": "[Deprecated: Is not used and will be removed in the future] Enables Prohibited Illegal Content guardrail" }, "prohibitedIllegalContentOptionSet": { "$ref": "#/components/schemas/GuardrailOptions", "deprecated": true, "description": "This guardrail is deprecated and will be removed in the future." }, "dangerousDrugUse": { "type": "boolean", "default": false, "deprecated": true, "description": "[Deprecated: Is not used and will be removed in the future] Enables Dangerous Drug Use guardrail" }, "dangerousDrugUseOptionSet": { "$ref": "#/components/schemas/GuardrailOptions", "deprecated": true, "description": "This guardrail is deprecated and will be removed in the future." } } }, "GuardrailOptions": { "type": "object", "properties": { "answer": { "type": "boolean", "description": "Whether the persona still sends a final message when this guardrail bans the user. Defaults to `true`." }, "banDurations": { "type": "array", "description": "Escalating ban durations for this guardrail, **in seconds** β€” up to 5 values.\nThe first applies to the user's first offence, the next to the following one; the last value repeats for every further offence.\nDefaults to `[7200, 43200, 86400, 172800, 3153600000]` (2h, 12h, 24h, 48h, permanent), or `[3153600000]` for the Underage guardrail.\nA permanent ban is the sentinel `3153600000` (about a century).\nThe dashboard takes these durations in hours and converts them for you.", "items": { "type": "integer", "format": "int64" }, "maxItems": 5, "minItems": 0 } } }, "PauseConversation": { "type": "object", "properties": { "duration": { "type": "integer", "format": "int32", "description": "Optional duration of the pause in seconds (maximum 12 hours). By default, the conversation will not be paused on DumGum side.", "maximum": 43200, "minimum": 1 } } }, "PersonaProfileOverrideSet": { "type": "object", "properties": { "sexualDrive": { "type": "string", "description": "\nThis parameter adjusts the Persona’s sexual appetite and likelihood to engage in sexting.\n\n| Value | Description |\n|-------------|--------------------------------------------------------------------------------------------|\n| `NONE` | The Persona will never send sexually explicit replies. |\n| `LOW` | The Persona will rarely initiate or respond to sexual topics, even if prompted. |\n| `NORMAL` | The Persona may engage in sexting if the conversation naturally leads there. |\n| `HIGH` | The Persona will respond positively and proactively to sexual cues from the User faster. |\n| `VERY_HIGH` | The Persona will initiate or escalate sexting as soon as the User shows any sexual intent. |\n", "enum": [ "VERY_HIGH", "HIGH", "NORMAL", "LOW", "NONE" ] } } }, "PostProcessingOptionSet": { "type": "object", "properties": { "greekRewrite": { "type": "boolean", "default": false, "description": "Used for Greek answer generations. Replace \";\" by \"?\" and accentuated characters by their non-accentuated equivalents." }, "russianRewrite": { "type": "boolean", "default": false, "description": "Used for Russian answer generations. Remove quotation marks the model places around individual slang words or short informal expressions, while leaving genuine quoted sentences intact." }, "romanianRewrite": { "type": "boolean", "default": false, "description": "Used for Romanian answer generations. Replace diacritical characters by their non-diacritical equivalents." }, "germanRewrite": { "type": "boolean", "default": false, "description": "Used for German answer generations (including Austria and Switzerland). Remove apostrophes from the chat forms gehts, gibts, wenns, sichs and habs, preserving quotations and structured text." } } }, "ShareablePicture": { "type": "object", "properties": { "id": { "type": "string", "description": "Your identifier for this picture.\nKeep it stable across requests: we use it to remember which pictures have already been shared in the conversation, so a changing id makes the persona offer the same picture again.", "maxLength": 128, "minLength": 1 }, "url": { "type": "string", "description": "URL we fetch the picture from. Maximum 512 characters. HTTPS is strongly recommended.", "maxLength": 512, "minLength": 1 }, "caption": { "type": "string", "description": "A custom caption of the picture, this can be used to override the default caption generated by our AI.", "maxLength": 100, "minLength": 1 } }, "required": [ "id", "url" ] }, "ShareableVideo": { "type": "object", "properties": { "id": { "type": "string", "description": "Your identifier for this video.\nKeep it stable across requests: we use it to remember which videos have already been shared in the conversation, so a changing id makes the persona offer the same video again.", "maxLength": 128, "minLength": 1 }, "url": { "type": "string", "description": "URL we fetch the video from. Maximum 512 characters. HTTPS is strongly recommended.", "maxLength": 512, "minLength": 1 }, "caption": { "type": "string", "description": "A custom caption of the video, this can be used to override the default caption generated by our AI.", "maxLength": 100, "minLength": 1 } }, "required": [ "id", "url" ] }, "UserPhotoReaction": { "type": "object", "properties": { "source": { "type": "string", "description": "The source of the photo.", "enum": [ "PROFILE_PICTURE", "URL" ] }, "url": { "type": [ "string", "null" ], "default": null, "description": "The URL of the photo. Required when `source` is set to `URL`." }, "caption": { "type": [ "string", "null" ], "default": null, "description": "Optional caption describing the photo. When set (non-blank), it is used as the photo description instead of the automatic vision analysis." } }, "required": [ "source" ] }, "VisionOptionSet": { "type": "object", "properties": { "userProfilePictureAnalysis": { "type": "boolean", "default": false, "description": "Enable user profile's picture analysis." }, "personaProfilePictureAnalysis": { "type": "boolean", "default": false, "description": "Enable persona profile's picture analysis." }, "sharedPicturesAnalysis": { "type": "boolean", "default": false, "description": "Enable user's shared pictures analysis.\nThe pictures are analysed on their own, but comparing them against the user's profile picture (so the persona can tell whether it is the same person) also requires `userProfilePictureAnalysis`." }, "sharedVideosAnalysis": { "type": "boolean", "default": false, "description": "Enable user's shared videos analysis." }, "shareablePicturesAnalysis": { "type": "boolean", "description": "Enable persona's shareable pictures analysis, this will allows our chat model to understand each image it is sharing." }, "shareableVideosAnalysis": { "type": "boolean", "default": false, "description": "Enable persona's shareable videos analysis, this will allows our chat model to understand each video it is sharing. Videos carrying a caption are never analyzed." } } }, "GenerateResponse": { "type": "object", "properties": { "answers": { "type": "array", "description": "The generated answers, in delivery order. A reply can contain several of them when the persona sends multiple messages in a row.", "items": { "$ref": "#/components/schemas/ContentCreationAnswer" } } }, "required": [ "answers" ] }, "ContentCreationConversationEnqueueRequest": { "type": "object", "description": "Represents a request to enqueue a conversation", "properties": { "userProfileId": { "type": "string", "description": "A user profile ID; this will represent the profile that will receive the generated reply." }, "personaProfileId": { "type": "string", "description": "A persona profile ID; this will represent the profile that our operator will impersonate." }, "language": { "type": "string", "description": "The language used to generate the reply.", "enum": [ "EN", "EN_GB", "FR", "FR_BE", "RO", "NL", "ES", "DE", "DE_CH", "DE_AT", "IT", "ES_LATAM", "BG", "HE", "JA", "NL_BE", "EN_AU", "PT_PT", "PT_BR", "SV_SE", "DA_DK", "FI_FI", "PL_PL", "LT_LT", "NB_NO", "NN_NO", "SL_SI", "HU", "HU_HU", "CS_CZ", "EL_GR", "EL_GR_LATIN", "EL_GR_GREEK", "HR_HR", "TR_TR", "EN_IE", "AF_ZA", "ZU_ZA", "LV_LV", "SK_SK", "GA_IE", "SR_RS", "ET_EE", "EN_CA", "FR_CA", "RU_RU", "UA_UA" ] }, "additionalLanguages": { "type": "array", "description": "A list of additional languages that can be used to generate the reply. Currently, we support only one additional language.", "items": { "type": "string", "enum": [ "EN", "EN_GB", "FR", "FR_BE", "RO", "NL", "ES", "DE", "DE_CH", "DE_AT", "IT", "ES_LATAM", "BG", "HE", "JA", "NL_BE", "EN_AU", "PT_PT", "PT_BR", "SV_SE", "DA_DK", "FI_FI", "PL_PL", "LT_LT", "NB_NO", "NN_NO", "SL_SI", "HU", "HU_HU", "CS_CZ", "EL_GR", "EL_GR_LATIN", "EL_GR_GREEK", "HR_HR", "TR_TR", "EN_IE", "AF_ZA", "ZU_ZA", "LV_LV", "SK_SK", "GA_IE", "SR_RS", "ET_EE", "EN_CA", "FR_CA", "RU_RU", "UA_UA" ] }, "maxItems": 1, "minItems": 0 }, "userProfileVersion": { "type": [ "string", "null" ], "description": "Specify the current user profile version. If it differs from the stored version, it will trigger a profile data refresh." }, "personaProfileVersion": { "type": [ "string", "null" ], "description": "Specify the current persona profile version. If it differs from the stored version, it will trigger a profile data refresh." }, "tags": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "A map of tags to associate with the generated answer. You can use any key-value pair to store additional information along with your request.\nYou can use this to store arbitrary metadata, for events tracking or statistics." }, "testMode": { "type": [ "boolean", "null" ], "description": "Specify whether the conversation should be processed in test mode. In test mode, you will receive a dummy answer, which is useful for testing purposes.\n\u003E **You will not be charged** when using test mode." }, "replyParameters": { "type": [ "object", "null" ], "$ref": "#/components/schemas/ContentCreationQueueConversationReplyParameterSet", "description": "A set of parameters that allow you to customize the reply you receive from us, enabling greater flexibility and control over the response format, content, and behavior." } }, "required": [ "language", "personaProfileId", "userProfileId" ] }, "Statistics": { "type": "object", "description": "\nUsage and cost for a project over the requested range, split into buckets plus a grand total.\n\nEvery amount is in your account currency, as a decimal string so no precision is lost when you parse it.\n", "properties": { "rows": { "type": "array", "description": "One entry per bucket that recorded activity, most recent first. Buckets with no activity at all are omitted.", "items": { "$ref": "#/components/schemas/StatisticsRow" } }, "total": { "$ref": "#/components/schemas/StatisticsMetrics", "description": "The same metrics summed over every returned bucket, so you don't have to add up `rows` yourself." } }, "required": [ "rows", "total" ] }, "StatisticsMetrics": { "type": "object", "description": "\nWhat the project used and what it cost, over one bucket or over the whole requested range.\n\nCounts are integers. Amounts are in your account currency, as plain decimal strings (`21.25`, `0.0`) so no precision is lost when you parse them.\n", "properties": { "answerMessageCount": { "type": "integer", "format": "int64", "description": "How many of your users' messages the answers of this bucket replied to.", "examples": [ "1420" ] }, "answerHumanCount": { "type": "integer", "format": "int64", "description": "Answers written by a human operator, in `HUMAN` reply mode.", "examples": [ "12" ] }, "answerHumanCost": { "type": "string", "description": "What those human-written answers cost you.", "examples": [ "0.3" ] }, "answerAiCount": { "type": "integer", "format": "int64", "description": "Answers generated by the model, in `AI` reply mode.", "examples": [ "838" ] }, "answerAiCost": { "type": "string", "description": "What those AI answers cost you.", "examples": [ "20.95" ] }, "messageDroppedCount": { "type": "integer", "format": "int64", "description": "Generation requests that ended without a reply β€” dropped by a guardrail, or with nothing to answer. Not billed.", "examples": [ "7" ] }, "answerActionCount": { "type": "integer", "format": "int64", "description": "Answers carrying an action rather than a text reply (`ACTION_*` types: pokes, picture requests, profile reports, …).", "examples": [ "23" ] }, "cost": { "type": "string", "description": "\nEverything billed on the answers of this bucket β€” AI and human replies, plus any Smart Fetch performed while writing them. This is the figure to use for a project's answer spend.\n\nMedia analyses and suggestion requests are billed outside of answers, so they are **not** part of this amount. They appear here as counts (`photoAnalysisCount`, `videoAnalysisCount`, `audioAnalysisCount`, `icebreakerSuggestionCount`, `followupSuggestionCount`) β€” multiply them by your per-unit price to get their spend.\n", "examples": [ "21.25" ] }, "answerFreeCount": { "type": "integer", "format": "int64", "description": "Answers that were not billed β€” mostly the follow-up messages of a multi-message reply, which is billed once on the first answer.", "examples": [ "134" ] }, "photoAnalysisCount": { "type": "integer", "format": "int64", "description": "Photo Analyses run on pictures your users sent. Billed outside of answers β€” see `cost`.", "examples": [ "58" ] }, "photoAnalysisCost": { "type": "number", "format": "double" }, "videoAnalysisCount": { "type": "integer", "format": "int64" }, "videoAnalysisCost": { "type": "number", "format": "double" }, "audioAnalysisCount": { "type": "integer", "format": "int64", "description": "Voice messages sent by users, transcribed and analysed so the persona could reply to what was actually said. A recording measured as carrying no signal at all β€” a muted or unplugged mic β€” is not analysed and not counted here.", "examples": [ "24" ] }, "audioAnalysisCost": { "type": "number", "format": "double" }, "webSearchCount": { "type": "integer", "format": "int64", "description": "Smart Fetch lookups performed while writing answers.", "examples": [ "16" ] }, "webSearchCost": { "type": "string", "description": "What those Smart Fetch lookups cost you. Already included in `cost`.", "examples": [ "0.8" ] }, "icebreakerSuggestionCount": { "type": "integer", "format": "int64", "description": "Icebreaker suggestions requested β€” a suggestion call on a conversation with no history. Billed outside of answers.", "examples": [ "31" ] }, "followupSuggestionCount": { "type": "integer", "format": "int64", "description": "Follow-up suggestions requested β€” a suggestion call on a conversation that already has messages. Billed outside of answers.", "examples": [ "44" ] } }, "required": [ "answerActionCount", "answerAiCost", "answerAiCount", "answerFreeCount", "answerHumanCost", "answerHumanCount", "answerMessageCount", "audioAnalysisCost", "audioAnalysisCount", "cost", "followupSuggestionCount", "icebreakerSuggestionCount", "messageDroppedCount", "photoAnalysisCost", "photoAnalysisCount", "videoAnalysisCost", "videoAnalysisCount", "webSearchCost", "webSearchCount" ] }, "StatisticsRow": { "type": "object", "description": "Usage and cost recorded for one bucket of the requested range.", "properties": { "date": { "type": "string", "description": "The bucket, as `YYYY-MM-DD`. With `groupBy=MONTHLY` this is the first day of that month.", "examples": [ "2026-07-14" ] }, "metrics": { "$ref": "#/components/schemas/StatisticsMetrics" } }, "required": [ "date", "metrics" ] }, "StatusResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK", "DEGRADED" ] } }, "required": [ "status" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Bearer authentication header of the form `Bearer \u003Ctoken\u003E`, where `\u003Ctoken\u003E` is an access key.\n\nExample: `Authorization: Bearer sk-proj-XXXXXXXXX`", "scheme": "bearer", "bearerFormat": "JWT | Access Key" } } }, "webhooks": { "ContentCreationProfileEndpoint": { "post": { "tags": [ "content-creation", "webhooks" ], "summary": "Get Profile Endpoint", "description": "Get a profile by ID.", "parameters": [ { "name": "profileId", "in": "query", "description": "This parameter will contain the profile ID required to retrieve the associated data.\n**Your endpoint must be able to handle this parameter.**", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Profile data fetched successfully. Your endpoint will respond with the appropriate JSON data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCreationProfileFetchResult" } } } } }, "servers": [ { "url": "https://yourdomain.com/your/path" } ] } }, "ContentCreationChatHistoryEndpoint": { "post": { "tags": [ "content-creation", "webhooks" ], "summary": "Get Chat History", "description": "Get the chat history for a given user and persona.", "parameters": [ { "name": "userProfileId", "in": "query", "description": "Your user profile id. The user profile interacting with the Persona profile.", "required": true, "schema": { "type": "string" } }, { "name": "personaProfileId", "in": "query", "description": "Your persona profile id. The profile for which the platform will generate responses.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chat history data fetched successfully. Your endpoint will respond with the appropriate JSON data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCreationChatHistoryResponse" } } } } }, "servers": [ { "url": "https://yourdomain.com/your/path" } ] } }, "ContentCreation.Webhooks.IncomingContent": { "post": { "tags": [ "content-creation", "webhooks" ], "summary": "Incoming Content", "description": "Receives events from our platform.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "event": { "type": "string", "description": "The name of the event.", "example": "answer.created" }, "data": { "$ref": "#/components/schemas/ContentCreationWebhookEvent", "description": "The data associated with the event." } } } } } }, "responses": { }, "servers": [ { "url": "https://yourdomain.com/your/path" } ] } } } }