Get Sponsored Prompt

POST

api

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
}
'

import requests

url = "https://dev.thrads.ai/api/v1/prompt/get-ad/"

payload = {
    "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
}
headers = {
    "thrads-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'thrads-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://dev.thrads.ai/api/v1/prompt/get-ad/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dev.thrads.ai/api/v1/prompt/get-ad/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "thrads-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://dev.thrads.ai/api/v1/prompt/get-ad/"

	payload := strings.NewReader("{\n  \"country_code\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"region\": \"<string>\",\n  \"city\": \"<string>\",\n  \"os\": \"<string>\",\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("thrads-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://dev.thrads.ai/api/v1/prompt/get-ad/")
  .header("thrads-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_code\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"region\": \"<string>\",\n  \"city\": \"<string>\",\n  \"os\": \"<string>\",\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.thrads.ai/api/v1/prompt/get-ad/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["thrads-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_code\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"region\": \"<string>\",\n  \"city\": \"<string>\",\n  \"os\": \"<string>\",\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "detail": [
      {
        "loc": [
          "<string>"
        ],
        "msg": "<string>",
        "type": "<string>"
      }
    ]
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

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

Pattern: ^[A-Za-z]{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 | null

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

Show child attributes

region

string | null

Region or state (optional).

city

string | null

City (optional).

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

AI-generated sponsored prompt with brand information and tracking capabilities for chatbot integration

Show child attributes

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
}
'

import requests

url = "https://dev.thrads.ai/api/v1/prompt/get-ad/"

payload = {
    "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
}
headers = {
    "thrads-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'thrads-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://dev.thrads.ai/api/v1/prompt/get-ad/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dev.thrads.ai/api/v1/prompt/get-ad/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "thrads-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://dev.thrads.ai/api/v1/prompt/get-ad/"

	payload := strings.NewReader("{\n  \"country_code\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"region\": \"<string>\",\n  \"city\": \"<string>\",\n  \"os\": \"<string>\",\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("thrads-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://dev.thrads.ai/api/v1/prompt/get-ad/")
  .header("thrads-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_code\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"region\": \"<string>\",\n  \"city\": \"<string>\",\n  \"os\": \"<string>\",\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.thrads.ai/api/v1/prompt/get-ad/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["thrads-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_code\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"region\": \"<string>\",\n  \"city\": \"<string>\",\n  \"os\": \"<string>\",\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "detail": [
      {
        "loc": [
          "<string>"
        ],
        "msg": "<string>",
        "type": "<string>"
      }
    ]
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

Introduction

Sponsored Messages

Sponsored Prompts

Authorizations

Body

Response