Skip to main content
POST
/
api
/
v1
/
iframes
Create Iframe Widget
curl --request POST \
  --url https://api.example.com/api/v1/iframes \
  --header 'Content-Type: application/json' \
  --data '
{
  "api_key_id": "<string>",
  "name": "<string>",
  "appearance": {},
  "behavior": {},
  "security": {}
}
'
{
  "id": "<string>",
  "name": "<string>",
  "status": "<string>",
  "embed_snippet": "<string>"
}

​
Request

​
api_key_id
string
required
The API key ID to link this widget to. The widget uses this key’s credits, Brand Soul, and allowed origins.
​
name
string
Display name for the widget. Default: "My Widget".
​
appearance
object
Visual customization: primaryColor, position (bottom-right | bottom-left), borderRadius, fontFamily, custom CSS overrides.
​
behavior
object
Behavioral settings: welcomeMessage, placeholder, maxPromptLength, enableFileUpload, enableVoice, strictAbuse (enables rate-limiting heuristics).
​
security
object
Security settings: requireTurnstile (bot protection), allowedOrigins (domain allowlist override).

​
Response

​
id
string
The widget config UUID. Use this as the configId in the embed script.
​
name
string
Widget display name.
​
status
string
"active" or "disabled".
​
embed_snippet
string
Ready-to-use HTML <script> tag for embedding on your site.

​
Authentication

Requires a dashboard session.

​
Example

curl
curl -X POST https://www.hitheo.ai/api/v1/iframes \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key_id": "key_abc123",
    "name": "Support Widget",
    "appearance": { "primaryColor": "#715eac" },
    "behavior": { "welcomeMessage": "Hi! How can I help?", "strictAbuse": true }
  }'