> ## 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 Prompt



## OpenAPI

````yaml POST /api/v1/prompt/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/prompt/get-ad/:
    post:
      tags:
        - Prompt V1
        - sponsored-chatbot-prompt
      summary: Get Sponsored Chatbot Prompt
      operationId: get_sponsored_chatbot_prompt_api_v1_prompt_get_ad__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SponsoredChatbotPromptRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SponsoredPromptResponse'
        '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:
    SponsoredChatbotPromptRequest:
      properties:
        userId:
          anyOf:
            - type: string
            - type: 'null'
          title: User ID
          description: >-
            Optional unique identifier for the user. Provide the same value for
            the same user across conversations.
        chatId:
          anyOf:
            - type: string
            - type: 'null'
          title: Chat ID
          description: >-
            Optional identifier for the chat session or conversation. Use the
            same value within the same conversation.
        content:
          anyOf:
            - 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
            - type: 'null'
          title: Content
          description: >-
            Conversation context MUST contain exactly two fields: 'user' and
            'chatbot', both populated with strings representing the latest
            message exchange
        country_code:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
          title: Country Code
          description: ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB').
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
          description: Region or state (optional).
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
          description: City (optional).
        os:
          anyOf:
            - type: string
            - type: 'null'
          title: OS
          description: Operating system of the client (optional).
        force:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Force
          description: >-
            If true forces ad generation; if false inhibits it; null for default
            behavior.
        conversationOffset:
          type: integer
          maximum: 20
          minimum: 0
          title: Conversation Offset
          description: >-
            Number of conversation turns to wait before showing the first ad.
            Ignored when the sponsored prompt is used as an opener (only
            relevant mid-conversation).
          default: 2
        adFrequencyLimit:
          type: integer
          maximum: 20
          minimum: 0
          title: Ad Frequency Limit
          description: >-
            Number of turns to wait before showing the next ad. Ignored when the
            sponsored prompt is used as an opener (only relevant
            mid-conversation).
          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. Ignored
            when the sponsored prompt is used as an opener (only relevant
            mid-conversation).
          default: false
      additionalProperties: false
      type: object
      required:
        - country_code
      title: SponsoredChatbotPromptRequest
      description: >-
        Request model for sponsored chatbot prompts with conversation context
        and targeting options
    SponsoredPromptResponse:
      allOf:
        - $ref: '#/components/schemas/APIResponse'
        - properties:
            data:
              $ref: '#/components/schemas/SponsoredPromptData'
      title: SponsoredPromptResponse
    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: ''
    SponsoredPromptData:
      properties:
        prompt:
          type: string
          title: Prompt
          description: The generated prompt
        link:
          type: string
          title: Link
          description: Clickable URL for the sponsored content or product page
        brand:
          type: string
          title: Brand
          description: Brand or company name associated with the sponsored content
        icon:
          type: string
          title: Icon
          description: URL to the ad icon image
        sponsored_prompt_id:
          type: string
          title: Sponsored Prompt ID
          description: ID of the sponsored prompt
      type: object
      required:
        - prompt
        - link
        - brand
        - sponsored_prompt_id
      title: SponsoredPromptData
      description: >-
        AI-generated sponsored prompt with brand information and tracking
        capabilities for chatbot integration
    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.

````