apidirect-io Truthsocial API

openapi: 3.2.0
info:
  title: Apidirect Io Truth Social API
  version: 1.9.1
  contact:
    name: API Direct support
    url: https://apidirect.io
    email: support@apidirect.io
  termsOfService: https://apidirect.io/terms
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  x-logo:
    url: https://apidirect.io/static/A.png
    altText: API Direct
  description: 'Operations tagged Truth Social across 2 of this provider''s published API definitions: apidirect-io-openapi.json, apidirect-io-x402-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://apidirect.io
  description: Production
- description: x402 (pay per request in USDC, no API key)
  url: https://x402.apidirect.io
tags:
- name: truthsocial
  description: Fetch any public Truth Social user's recent posts by username. Post text, engagement metrics, media attachments and hashtags.
paths:
  /v1/truthsocial/user/posts:
    get:
      tags:
      - truthsocial
      operationId: truthsocialUserPosts
      summary: Truth Social User Posts
      description: 'Get a single Truth Social user''s recent posts (their feed) by username. Returns post text, engagement metrics (replies, reposts, likes), media attachments (image, video and other Mastodon-style types), hashtags, language, visibility, reply status and a direct link to each post. Set get_sentiment=true to add AI emotion analysis (+$0.001/page).


        **Price:** $0.006 per page. **Free tier:** 50 requests/month.'
      externalDocs:
        url: https://apidirect.io/docs/truthsocial-user-posts
      parameters:
      - name: username
        in: query
        required: true
        description: Truth Social username, with or without leading @ (max 100 characters)
        schema:
          type: string
          maxLength: 100
        example: realDonaldTrump
      - name: pages
        in: query
        required: false
        description: Number of pages to fetch and merge into one response (1-20, billed per page). Each page returns up to 20 posts. Fetching stops early when there are no more results.
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 1
        example: 2
      - name: get_sentiment
        in: query
        required: false
        description: 'Set to true to add AI emotion analysis to each post. Adds a `sentiment` object containing `emotions` (joy, trust, fear, surprise, sadness, disgust, anger and anticipation, each scored 0-100), `dominant_emotion`, `emotional_intensity` (0-10), and `polarity` (positive, negative or neutral). Any post that cannot be scored returns `sentiment: null`.'
        schema:
          type: boolean
          default: false
      x-example-query:
        username: realDonaldTrump
        pages: 2
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TruthsocialUserPostsResponse'
              example:
                count: 40
                pages: 2
                username: realDonaldTrump
                posts:
                - title: '@realDonaldTrump on Truth Social'
                  url: https://truthsocial.com/@realDonaldTrump/117043133534824966
                  date: '2026-08-05 13:28:05'
                  author: realDonaldTrump
                  source: Truth Social
                  domain: truthsocial.com
                  snippet: Thank you for your attention to this matter! President DJT
                  likes: 5514
                  replies: 567
                  reposts: 1399
                  post_id: '117043133534824966'
                  content_html: <p>Thank you for your attention to this matter! President DJT</p>
                  media:
                  - media_id: '117041192378469520'
                    type: video
                    url: https://static-assets-1.truthsocial.com/media_attachments/files/117/041/192/original/9cbc020383d40cd5.mp4
                    description: ''
                  hashtags: []
                  language: en
                  visibility: public
                  sensitive: false
                  spoiler_text: ''
                  sponsored: false
                  is_reply: false
                  in_reply_to_id: ''
        '400':
          description: 'Bad request: a required parameter is missing or a value is invalid (code: missing_parameter or invalid_parameter).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'Unauthorized: the API key is missing or invalid (code: missing_api_key or invalid_api_key).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Free tier used up for this endpoint and no payment method on file (`payment_required`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Account blocked after a failed payment (`account_blocked`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Not found: the user does not exist or could not be resolved (code: not_found).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded, or too many concurrent requests for this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'Internal server error (code: server_error).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Temporary failure retrieving Truth Social data. Please retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable. Please retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://apidirect.io
      description: Production
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - code
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code, such as `missing_parameter`, `invalid_parameter`, `missing_api_key`, `invalid_api_key`, `payment_required`, `account_blocked`, `not_found`, `concurrency_limit_exceeded`, `daily_limit_exceeded`, `monthly_limit_exceeded`, `upstream_rate_limit`, `upstream_error`, `upstream_timeout`, `service_unavailable`, `endpoint_suspended`, `payload_too_large` or `rate_limited`. New codes may be added.
      example:
        error: 'Missing required parameter: query'
        code: missing_parameter
    TruthsocialUserPostsResponse:
      type: object
      properties:
        count:
          type:
          - number
          - 'null'
        pages:
          type:
          - number
          - 'null'
        username:
          type:
          - string
          - 'null'
        posts:
          type:
          - array
          - 'null'
          items:
            type:
            - object
            - 'null'
            properties:
              title:
                type:
                - string
                - 'null'
              url:
                type:
                - string
                - 'null'
              date:
                type:
                - string
                - 'null'
              author:
                type:
                - string
                - 'null'
              source:
                type:
                - string
                - 'null'
              domain:
                type:
                - string
                - 'null'
              snippet:
                type:
                - string
                - 'null'
              likes:
                type:
                - number
                - 'null'
              replies:
                type:
                - number
                - 'null'
              reposts:
                type:
                - number
                - 'null'
              post_id:
                type:
                - string
                - 'null'
              content_html:
                type:
                - string
                - 'null'
              media:
                type:
                - array
                - 'null'
                items:
                  type:
                  - object
                  - 'null'
                  properties:
                    media_id:
                      type:
                      - string
                      - 'null'
                    type:
                      type:
                      - string
                      - 'null'
                    url:
                      type:
                      - string
                      - 'null'
                    description:
                      type:
                      - string
                      - 'null'
              hashtags:
                type:
                - array
                - 'null'
                items: {}
              language:
                type:
                - string
                - 'null'
              visibility:
                type:
                - string
                - 'null'
              sensitive:
                type:
                - boolean
                - 'null'
              spoiler_text:
                type:
                - string
                - 'null'
              sponsored:
                type:
                - boolean
                - 'null'
              is_reply:
                type:
                - boolean
                - 'null'
              in_reply_to_id:
                type:
                - string
                - 'null'
      description: Inferred from a live response. Any field can be null or absent, and new fields may be added at any time.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key (starts with `ak_live_`), from https://apidirect.io/dashboard/keys.
externalDocs:
  description: API Direct documentation
  url: https://apidirect.io/docs
x-refined-from:
- apidirect-io-openapi.json
- apidirect-io-x402-openapi.json