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.

Auth: public key, or public key + userHash, or public key + server API key.

Parameters

  • {surface}"banner" | "dashboard_card" | "modal" | "notification" | "email"required

    Where the message appears. Any other value is a 400 that lists these.

  • ?publicKeystringrequired

    The project's public key.

  • ?userIdstringrequired

    The end user's distinct id, up to 256 characters. "undefined" and "null" are refused.

  • ?userHashstring

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

  • ?shownboolean

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

Errors: invalid_json (400), invalid_request (400), missing_public_key (400), unknown_surface (400), invalid_public_key (401), invalid_api_key (401), missing_user_hash (401), invalid_user_hash (401), server_key_required (401), trial_expired (402), billing_inactive (402), plan_limit_reached (402), origin_not_allowed (403), api_key_project_mismatch (403), payload_too_large (413), rate_limited (429), internal_error (500), service_unavailable (503).

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.

Auth: public key, or public key + userHash, or public key + server API key.

Body

  • publicKeystringrequired

    The project's public key (phk_live_…) from its project page. max 200 chars

  • distinctIdstring | number

    Your 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 | numberdeprecated

    Old name for distinctId. max 256 chars

  • action"shown" | "dismissed" | "clicked" | "converted"required

  • logIdinteger | string

    The decision's logId (a numeric string is accepted).

  • recommendationIdstring

    The decision's id; uses the user's latest serve of it.

  • userHashstring

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

Errors: invalid_json (400), invalid_request (400), missing_public_key (400), holdout_feedback (400), invalid_public_key (401), invalid_api_key (401), missing_user_hash (401), invalid_user_hash (401), origin_not_allowed (403), api_key_project_mismatch (403), decision_not_found (404), payload_too_large (413), rate_limited (429), internal_error (500), service_unavailable (503).

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides