API & Webhooks

Overview

TruthPush delivers enriched post events — sentiment, signed score, tickers, and keywords — through two integration paths:

• Webhooks push JSON to your URL in real time when a monitored profile posts (Business+).
• REST catch-up polls chronological posts with cursor pagination when you need to backfill or recover missed events (Business+).
• Generate your API token and configure your webhook URL in TruthTerminal after upgrading to Business.

Telegram and email alerts use separate channels; this reference covers programmatic access only.

Authentication

REST requests use a Bearer token. The same secret signs webhook payloads.

1. Upgrade to Business or Enterprise.
2. Open TruthTerminal → Developer Hub → Generate API Key.
3. Send Authorization: Bearer YOUR_API_TOKEN on every REST request.

curl "https://truthpush.com/api/v1/posts/catch-up?handle=realDonaldTrump&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Treat your API token like a password. Regenerating invalidates the previous token and webhook signatures immediately.

Webhooks

Configure your webhook URL in TruthTerminal after generating an API token. Each qualifying post triggers an HTTP POST with a JSON body and TruthPush signature headers. The API token is required — deliveries are always signed.

Request headers

POST https://your-server.com/hooks/truthpush
Content-Type: application/json
X-TruthPush-Signature: t=<unix>,v1=<hmac_sha256_hex>
X-TruthPush-Event-Id: <post_id>

v1 = HMAC_SHA256(api_token, "<t>." + raw_body)

Verify the signature (Python)

Reference implementation for receivers — checks the replay window and compares the signature in constant time.

import hmac
import hashlib
import time

TOLERANCE_SECONDS = 300  # reject requests older than 5 minutes

def verify_signature(payload: bytes, secret: str, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp, signature = int(parts["t"]), parts["v1"]

    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False  # possible replay attack

    signed_payload = f"{timestamp}.".encode() + payload
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask example
# signature_header = request.headers["X-TruthPush-Signature"]
# if not verify_signature(request.get_data(), API_TOKEN, signature_header):
#     abort(401)

Signal filter

Set a minimum absolute signed_score (0 = all events, 0.7 = strong signals only) in TruthTerminal to reduce noise in trading pipelines.

Delivery speed

Each qualifying post triggers exactly one webhook delivery — the raw post plus the finished sentiment read, sent as soon as our AI enrichment completes (usually within a couple of seconds). Delivery runs on its own queue, so it is never held up by Telegram or email delivery to other users.

Retries

Temporary failures (network errors, 5xx, 408, 429) are retried automatically after 60 seconds, then 5 minutes, then 15 minutes (up to three retries). Permanent client errors (other 4xx) are not retried — fix the endpoint and wait for the next event, or use REST catch-up.

REST API

GET /api/v1/posts/catch-up

Returns posts for a handle in ascending chronological order with cursor pagination. Responses are short-cached (~7s) and support ETag / If-None-Match for efficient polling.

Query parameters

• handle — Truth Social username without @ (required). Use all (or omit meaningful handles) for your full watchlist. Handles outside your watchlist return an empty list — they are never expanded to other profiles.
• since — ISO 8601 anchor for the first request (optional)
• cursor — opaque value from meta.next_cursor (optional)
• limit — 1–200, default 100

Pagination example

Start with the first request without a cursor. Every response includes meta.next_cursor — pass it unchanged into the next request until it is null.

# 1) First request — no cursor yet
curl "https://truthpush.com/api/v1/posts/catch-up?handle=realDonaldTrump&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response (truncated):
# { "posts": [ … 100 items … ],
#   "meta": { "next_cursor": "eyJpZCI6MTIzNDU2fQ==" } }

# 2) Follow-up request — pass the cursor from meta.next_cursor
curl "https://truthpush.com/api/v1/posts/catch-up?handle=realDonaldTrump&cursor=eyJpZCI6MTIzNDU2fQ%3D%3D&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# meta.next_cursor is null once you've reached the latest post

Event object

Webhook and REST share the same enrichment fields (sentiment, signed_score, score, tickers, keywords, reasoning, media). The envelope differs: webhooks use event_id, target, post_id, and url; REST catch-up uses id and user_handle (plus display metadata). For webhooks, event_id equals post_id — use it for idempotent processing on your side.

{
  "event_id": "1234567890",
  "target": "realdonaldtrump",
  "post_id": "1234567890",
  "content": "Post text…",
  "url": "https://truthsocial.com/@realdonaldtrump/posts/1234567890",
  "media": [],
  "sentiment": "bullish",
  "signed_score": 0.89,
  "score": 0.89,
  "tickers": ["$DJT"],
  "keywords": ["tariffs", "trade"],
  "reasoning": "Direct market impact via trade policy.",
  "ai_analysis": { … }
}

event_id

Stable event ID — use for idempotent processing

target

Monitored Truth Social handle

sentiment

bullish | bearish | neutral

signed_score

Directional score from −1 to +1

tickers

Extracted tickers (e.g. DJT) — not a trading signal product

keywords

Detected keywords from post content

ai_analysis

Legacy nested object — identical data, kept for backward compatibility

Rate limits

Limits apply per API token. Exceeding them returns HTTP 429 with Retry-After.

• Business: 60 requests/minute · 10,000/day
• Enterprise: 300 requests/minute · 500,000/day
• Responses include X-RateLimit-* headers.

Plans & access

API and webhooks are not available on Observer or Professional. TruthTerminal live feed is available from Professional; programmatic access starts at Business.

Errors

Common API responses:

• 401 — missing or invalid Bearer token
• 403 — tier does not include API access
• 429 — rate limit exceeded; honor Retry-After
• 400 — invalid cursor or upgrade_required_* from archive window