Skip to main content
API reference

Quick start · Truth Social

Truth Social WebSocket API quick start

Connect to your account's Truth Social stream and receive posts, retruths and quotes from the accounts you track as JSON. This page gets a consumer running; the API reference holds every field.

From $300/month for 5 accounts · WebSocket +$150/month · Trump and White House ~50ms · others under a second
View Truth Social pricingFull Truth Social reference
WebSocket
wss://truth.1322.io/{ws_path}?key={ws_key}
REST base
https://truth.1322.io
Auth
X-Api-Key header (REST), ?key= (WebSocket)
Updated

What you get

Posts, retruths and quotes (including a quote of a quote), link cards and media from the Truth Social accounts on your list. A retruth or quote names its original author, so the whole chain is in one frame.

The priority Trump and White House accounts average around 50ms; other tracked accounts arrive in under a second.

Price: From $300/month for 5 accounts; WebSocket +$150/month. Plans: Lite $300/month (5 accounts), Standard $450/month (15 accounts), Pro $700/month (30 accounts). Pay monthly, or prepay 3 months (10% off), 6 months (15% off) or a year (25% off). See Truth Social pricing.

Authentication

  • REST calls send your API key in the X-Api-Key header. Every endpoint except /health needs it.
  • The WebSocket takes your WS key as ?key= on your account's own path: wss://truth.1322.io/{ws_path}?key={ws_key}.
  • The API key, ws_path and WS key are on the API access page in your dashboard; its Copy URL button gives the complete WebSocket URL.

Connect to the WebSocket

Set these environment variables, then run either consumer from your server:

  • TRUTH_WS_PATH: your ws_path
  • TRUTH_WS_KEY: your WS key
  • TRUTH_API_KEY: your API key (REST only)
# pip install "websockets>=13"   (Python 3.9+)
import asyncio, json, os
from websockets.asyncio.client import connect

# ws_path and WS key: the API access page in your dashboard
WS_PATH = os.environ["TRUTH_WS_PATH"].strip("/")
WS_URL = "wss://truth.1322.io/" + WS_PATH + "?key=" + os.environ["TRUTH_WS_KEY"]

def handle(post):
    if post.get("platform") != "truth":
        return
    kind = "retruth" if post.get("is_retruth") else "quote" if post.get("is_quote") else "post"
    print(kind, post.get("username"), post.get("key"), (post.get("text") or "")[:80])

async def main():
    backoff = 1
    while True:
        try:
            async with connect(WS_URL) as ws:
                backoff = 1
                async for raw in ws:
                    try:
                        event = json.loads(raw)
                    except ValueError:
                        continue
                    if isinstance(event, dict):
                        handle(event)
        except Exception as exc:
            print("disconnected:", exc)
        await asyncio.sleep(backoff)
        backoff = min(backoff * 2, 30)

asyncio.run(main())
// npm install ws, save as consumer.mjs, run: node consumer.mjs   (Node 18+)
import WebSocket from "ws"

// ws_path and WS key: the API access page in your dashboard
const WS_PATH = (process.env.TRUTH_WS_PATH ?? "").split("/").filter(Boolean).join("/")
const WS_KEY = process.env.TRUTH_WS_KEY
if (!WS_PATH || !WS_KEY) throw new Error("Set TRUTH_WS_PATH and TRUTH_WS_KEY")
const WS_URL = "wss://truth.1322.io/" + WS_PATH + "?key=" + encodeURIComponent(WS_KEY)

function handle(post) {
  if (post.platform !== "truth") return
  const kind = post.is_retruth ? "retruth" : post.is_quote ? "quote" : "post"
  console.log(kind, post.username, post.key, (post.text ?? "").slice(0, 80))
}

let backoff = 1000

function connect() {
  const ws = new WebSocket(WS_URL)
  ws.on("open", () => { backoff = 1000 })
  ws.on("message", (raw) => {
    let event
    try { event = JSON.parse(raw.toString()) } catch { return }
    if (event && typeof event === "object" && !Array.isArray(event)) handle(event)
  })
  ws.on("error", (err) => console.error("socket error:", err.message))
  ws.on("close", () => {
    setTimeout(connect, backoff)
    backoff = Math.min(backoff * 2, 30000)
  })
}

connect()
  • Each message is one JSON object for one post.
  • Events are not queued while you are disconnected, so reconnect promptly with a capped backoff, as above.

One example frame

Illustrative values for fictional accounts, trimmed to the fields most consumers read first. A real frame carries the full set for your tracked accounts.

{
  "platform": "truth",
  "username": "examplecampaign",
  "display_name": "Example Campaign",
  "user_avatar": "https://example.com/avatar.jpg",
  "user_following": 48,
  "user_followers": 125400,
  "user_id": "109000000000000001",
  "key": "115000000000000001",
  "timestamp": "2026-10-15T14:03:21Z",
  "seen_at": "2026-10-15T14:03:21Z",
  "text": "Town hall moves to Thursday at 7pm.",
  "media": [
    {
      "kind": "image",
      "url": "https://example.com/media/townhall.jpg",
      "poster_url": "",
      "created_at": "2026-10-15T14:03:21Z",
      "source": "own"
    }
  ]
}
  • key is the post ID: dedupe on it. seen_at is when 1322 recorded the post.
  • On a retruth, username is the account that retruthed and retruth_of is the original author. A quote carries is_quote and a quoted object, which can hold one nested quoted.

Manage the list over REST

REST base https://truth.1322.io. Each call below sends X-Api-Key with your API key.

MethodPathWhat it does
GET/v1/listThe accounts you track.
GET/v1/limitsTracked count, max_tracked and your per-key request rate (rpm).
POST/v1/trackAdd an account by handle.
POST/v1/untrackRemove an account by handle.
curl "https://truth.1322.io/v1/list" \
  -H "X-Api-Key: $TRUTH_API_KEY"

curl "https://truth.1322.io/v1/limits" \
  -H "X-Api-Key: $TRUTH_API_KEY"

curl -X POST "https://truth.1322.io/v1/track" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $TRUTH_API_KEY" \
  -d '{ "handle": "examplecampaign" }'

curl -X POST "https://truth.1322.io/v1/untrack" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $TRUTH_API_KEY" \
  -d '{ "handle": "examplecampaign" }'
  • GET /health is the one endpoint that needs no key. Errors use standard HTTP status codes (401, 403, 429).

Full reference

Every field, endpoint and edge case for Truth Social lives in the API reference. Jump straight to the part you need:

Common questions

Where do I find ws_path and the WS key?

On the API access page in your dashboard. Its Copy URL button gives the complete wss://truth.1322.io/{ws_path}?key={ws_key} URL; the REST API key is listed on the same page.

How do I tell a retruth from a quote?

A retruth sets is_retruth, retruth_of_id and retruth_of (the original author). A quote sets is_quote and a quoted object with the quoted post's key, text, URL and author; quoted.quoted holds a quote of a quote.

Other quick starts

Related: