Skip to main content
POST
/
api
/
v1
/
prompt
/
get-ad
Get Sponsored Chatbot Prompt
curl --request POST \
  --url https://dev.thrads.ai/api/v1/prompt/get-ad/ \
  --header 'Content-Type: application/json' \
  --header 'thrads-api-key: <api-key>' \
  --data '
{
  "country_code": "<string>",
  "userId": "<string>",
  "chatId": "<string>",
  "content": {
    "user": "<string>",
    "chatbot": "<string>"
  },
  "region": "<string>",
  "city": "<string>",
  "os": "<string>",
  "force": true,
  "conversationOffset": 2,
  "adFrequencyLimit": 5,
  "production": false
}
'
{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "success",
  "message": "<string>",
  "data": {
    "prompt": "<string>",
    "link": "<string>",
    "brand": "<string>",
    "sponsored_prompt_id": "<string>",
    "icon": "<string>"
  }
}

Authorizations

​
thrads-api-key
string
header
required

API key for authenticating requests to the Thrads API. You can obtain your API key from the Thrads Platform dashboard.

Body

application/json

Request model for sponsored chatbot prompts with conversation context and targeting options

​
country_code
string
required

ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB').

Required string length: 2
​
userId
string | null

Optional unique identifier for the user. Provide the same value for the same user across conversations.

​
chatId
string | null

Optional identifier for the chat session or conversation. Use the same value within the same conversation.

​
content
Content · object

Conversation context MUST contain exactly two fields: 'user' and 'chatbot', both populated with strings representing the latest message exchange

​
region
string | null

Region or state (optional).

​
city
string | null

City (optional).

​
os
string | null

Operating system of the client (optional).

​
force
boolean | null

If true forces ad generation; if false inhibits it; null for default behavior.

​
conversationOffset
integer
default:2

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).

Required range: 0 <= x <= 20
​
adFrequencyLimit
integer
default:5

Number of turns to wait before showing the next ad. Ignored when the sponsored prompt is used as an opener (only relevant mid-conversation).

Required range: 0 <= x <= 20
​
production
boolean
default:false

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).

Response

​
apiVersion
string
required

Version of the Thrads API being used

​
requestId
string
required

Unique identifier for this API request for tracking and debugging

​
timestamp
string<date-time>
required

ISO 8601 timestamp when the response was generated

​
docsUrl
string
required

URL to the API documentation for reference

​
totalTime
number
required

Total processing time for the request in seconds

​
status
enum<string>
required

Always 'success' for successful requests

Available options:
success
​
message
string
required

Human-readable message describing the successful response

​
data
SponsoredPromptData · object
required

Response payload containing the requested data AI-generated sponsored prompt with brand information and tracking capabilities for chatbot integration