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. Each qualifying post triggers an HTTP POST with a JSON body and TruthPush signature headers.

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)

Signal filter

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

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 — handle — Truth Social username without @ (required)
• since — since — ISO 8601 anchor for the first request (optional)
• cursor — cursor — opaque value from meta.next_cursor (optional)
• limit — limit — 1–200, default 100

Event object

Webhook payloads and REST post objects share the same enrichment fields. event_id equals post_id for deduplication 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