API reference
Decisions
Approved messages for a user and surface, and what happened to them.
Get a decision#
get/decisions/{surface}
The highest-priority approved message for this user and surface, or { "decision": null } (nothing approved, the user is in the holdout or was erased, or a cap applies). Safe to repeat: a serve counts toward billing and frequency caps when you report shown (POST /feedback), not when you fetch. holdoutLogIds lists control-group entries for messages that would have shown here: render nothing, and report shown for each when the slot renders, so both arms are counted the same way. A repeat fetch within 30 minutes returns the same logId. 1200 requests per minute per project, and 120 per end user.
Parameters
{surface}"banner" | "dashboard_card" | "modal" | "notification" | "email"requiredWhere the message appears. Any other value is a 400 that lists these.
?publicKeystringrequiredThe project's public key.
?userIdstringrequiredThe end user's distinct id, up to 256 characters. "undefined" and "null" are refused.
?userHashstringIdentity verification: lowercase hex HMAC-SHA256 of the user id, keyed with the project's identity secret, computed on your server. Required once the project turns on identity verification; ignored on server API key calls.
?shownbooleanServer API key calls that render the message straight away can send shown=true to count the serve now, instead of a separate POST /feedback.
curl "https://tughq.com/api/v1/decisions/banner?publicKey=phk_live_3kV9xQmR2pT8wYc1Ld5NbA&userId=user_123"200 response · JSON
{
"decision": {
"id": "8e1f4a2b-6c3d-4e5f-9a0b-1c2d3e4f5a6b",
"logId": 42,
"surface": "banner",
"title": "You're close, one step left",
"body": "Most teams that finish setup see their first result the same day.",
"ctaLabel": "Finish setup",
"ctaUrl": "/onboarding",
"priority": 0.8
}
}Report what happened to a decision#
post/feedback
Record shown (it rendered; this is what counts as a serve), dismissed, clicked or converted against a served decision. Send its logId, or its id as recommendationId to use the user's latest serve. Only shown is accepted for holdout entries. 300 requests per minute per project, and 60 per end user.
Body
publicKeystringrequiredThe project's public key (
phk_live_…) from its project page. max 200 charsdistinctIdstring | numberYour stable id for the end user. Numbers are converted to strings; surrounding spaces are trimmed. Don't use an email address or other personal data. Up to 256 characters.
userIdstring | numberdeprecatedOld name for distinctId. max 256 chars
action"shown" | "dismissed" | "clicked" | "converted"requiredlogIdinteger | stringThe decision's logId (a numeric string is accepted).
recommendationIdstringThe decision's id; uses the user's latest serve of it.
userHashstringIdentity verification: lowercase hex HMAC-SHA256 of the user id, keyed with the project's identity secret, computed on your server. Required once the project turns on identity verification; ignored on server API key calls.
curl -X POST "https://tughq.com/api/v1/feedback" \
-H "Content-Type: application/json" \
-d '{
"publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
"distinctId": "user_123",
"logId": 42,
"action": "clicked"
}'200 response · JSON
{
"ok": true
}