> ## Documentation Index > Fetch the complete documentation index at: https://publisher-docs.thrads.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Sponsored Message ## OpenAPI ````yaml POST /api/v1/message/get-ad/ openapi: 3.1.0 info: title: Thrads API description: Thrads API version: 0.0.1 servers: - url: https://dev.thrads.ai description: Production API server security: [] paths: /api/v1/message/get-ad/: post: tags: - Message V1 - sponsored-message summary: Get Sponsored Message operationId: get_sponsored_message_api_v1_message_get_ad__post requestBody: content: application/json: schema: $ref: '#/components/schemas/SponsoredMessageChatbotRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SponsoredMessageResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '422': description: '' content: application/json: schema: $ref: '#/components/schemas/APIValidationErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' security: - ApiKeyAuth: [] components: schemas: SponsoredMessageChatbotRequest: properties: userId: type: string maxLength: 100 title: User ID description: >- Unique identifier for the user requesting the sponsored message. Must be the same for the same user across all conversations. chatId: type: string maxLength: 100 title: Chat ID description: >- Unique identifier for the chat session or conversation. Must be the same across the same conversation. userRegion: anyOf: - type: string - type: 'null' title: User Region description: >- Geographic region of the user for localized ad targeting. Should be an ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE', 'JP') content: type: object properties: user: type: string description: The user's message in the conversation chatbot: type: string description: The chatbot's response message required: - user - chatbot additionalProperties: false title: Content description: >- Required conversation context MUST contain exactly two fields: 'user' and 'chatbot', both populated with strings representing the latest message exchange metaData: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: >- Additional context about user interests, conversation topic, or targeting preferences force: anyOf: - type: boolean - type: 'null' title: Force description: >- If set to true it forces the ad generation regardless of frequency limits or other constraints. If set to false it inhibits the ad generation. Default is set to null which does not affect the ad generation conversationOffset: type: integer maximum: 20 minimum: 0 title: Conversation Offset description: Number of conversation turns to wait before showing the first ad default: 2 adFrequencyLimit: type: integer maximum: 20 minimum: 0 title: Ad Frequency Limit description: Number of turns to wait before showing the next ad default: 5 production: type: boolean title: Production description: >- Whether this is a production request (true) or sandbox/testing (false). Only production requests count for monetization. default: false additionalProperties: false type: object required: - userId - chatId - content title: SponsoredMessageChatbotRequest description: >- Request model for sponsored chatbot messages with required conversation context and targeting options SponsoredMessageResponse: allOf: - $ref: '#/components/schemas/APIResponse' - properties: data: $ref: '#/components/schemas/SponsoredMessageData' title: SponsoredMessageResponse APIErrorResponse: properties: apiVersion: type: string title: API Version description: Version of the Thrads API being used requestId: type: string title: Request ID description: Unique identifier for this API request for tracking and debugging timestamp: type: string format: date-time title: Timestamp description: ISO 8601 timestamp when the error response was generated docsUrl: type: string title: Documentation URL description: URL to the API documentation for reference totalTime: type: number title: Total Time description: Total processing time before the error occurred in seconds status: type: string enum: - error title: Status description: Always 'error' for error responses message: type: string title: Message description: Human-readable error message describing what went wrong data: type: object title: Data description: Always empty object for error responses error: type: object properties: type: type: string title: Error Type description: Type of error that occurred code: type: integer title: Error Code description: Numeric error code for programmatic handling required: - type - code title: Error Details description: Structured error information with type and code type: object required: - apiVersion - requestId - timestamp - docsUrl - totalTime - status - message - data - error title: APIErrorResponse description: >- Standard error response wrapper for failed API requests with detailed error information APIValidationErrorResponse: properties: apiVersion: type: string title: API Version description: Version of the Thrads API being used requestId: type: string title: Request ID description: Unique identifier for this API request for tracking and debugging timestamp: type: string format: date-time title: Timestamp description: ISO 8601 timestamp when the validation error occurred docsUrl: type: string title: Documentation URL description: URL to the API documentation for reference totalTime: type: number title: Total Time description: Total processing time before validation failed in seconds status: type: string enum: - error title: Status description: Always 'error' for validation error responses message: type: string title: Message description: Human-readable validation error message data: type: object title: Data description: Always empty object for validation error responses error: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationError' title: Detail description: List of validation errors with field locations and messages required: - detail title: Validation Error Details description: Structured validation error information type: object required: - apiVersion - requestId - timestamp - docsUrl - totalTime - status - message - data - error title: APIValidationErrorResponse description: >- Standard validation error response wrapper with detailed field validation errors APIResponse: properties: apiVersion: type: string title: API Version description: Version of the Thrads API being used requestId: type: string title: Request ID description: Unique identifier for this API request for tracking and debugging timestamp: type: string format: date-time title: Timestamp description: ISO 8601 timestamp when the response was generated docsUrl: type: string title: Documentation URL description: URL to the API documentation for reference totalTime: type: number title: Total Time description: Total processing time for the request in seconds status: type: string enum: - success title: Status description: Always 'success' for successful requests message: type: string title: Message description: Human-readable message describing the successful response data: type: object title: Data description: Response payload containing the requested data type: object required: - apiVersion - requestId - timestamp - docsUrl - totalTime - status - message - data title: APIResponse description: '' SponsoredMessageData: properties: creative: type: string title: Creative description: The message text generated prod_name: type: string title: Product Name description: Name of the sponsored product or service img_url: type: string title: Image URL description: >- URL to the product image. The image is a png file with aspect ratio 1:1 and resolution of 224x224 prod_url: type: string title: Product URL description: Landing page URL for the sponsored product type: object required: - creative - prod_name - img_url - prod_url title: SponsoredMessageData description: '' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: apiKey in: header name: thrads-api-key description: >- API key for authenticating requests to the Thrads API. You can obtain your API key from the [Thrads Platform](https://platform.thrads.ai) dashboard. ````