InsightSocial Truthsocial API

openapi: 3.2.0
info:
  title: Insightsocial App Truthsocial API
  version: 2.0.0
  description: 'Operations tagged truthsocial across 2 of this provider''s published API definitions: openapi.json, insightsocial-app-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.insightsocial.app
security:
- apiKey: []
tags:
- name: truthsocial
paths:
  /v1/truthsocial/profile:
    get:
      operationId: truthsocial_profile
      summary: Profile
      description: 'Returns a Truth Social user''s public profile: display name, follower count, following count, truth count, bio, and profile image URL.


        Use it for a quick profile snapshot; use user/posts for that account''s recent truths.


        **10 credits** per call.'
      tags:
      - truthsocial
      parameters:
      - name: handle
        in: query
        required: true
        description: Truth Social username without the @ symbol
        schema:
          type: string
          example: realDonaldTrump
      - name: max_age_s
        in: query
        required: false
        description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 900 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
        schema:
          type: integer
          minimum: 0
          maximum: 3600
      - name: dry_run
        in: query
        required: false
        description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
        schema:
          type: string
          enum:
          - '1'
      x-credits: 10
      x-group: Profile
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope2'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/ProfileOne'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
      x-stability: stable
    servers:
    - url: https://api.insightsocial.app
  /v1/truthsocial/user/posts:
    get:
      operationId: truthsocial_user_posts
      summary: User › Posts
      description: 'Returns a Truth Social user''s recent truths: text content, like count, retruth count, reply count, media attachments, and creation timestamp.


        Use it to list an account''s recent truths; use post when you already have a single truth''s URL.


        **10 credits** per call.


        Paginates by `cursor`: see Pagination.'
      tags:
      - truthsocial
      parameters:
      - name: handle
        in: query
        required: false
        description: 'Truth Social username without the @ symbol. Provide at least one of: `handle`, `user_id`.'
        schema:
          type: string
          example: realDonaldTrump
      - name: user_id
        in: query
        required: false
        description: 'Truth Social user id, the `id` field from /v1/truthsocial/profile. Faster than handle. Provide at least one of: `handle`, `user_id`.'
        schema:
          type: string
      - name: trim
        in: query
        required: false
        description: Set to true for a lighter record with fewer fields.
        schema:
          type: boolean
      - name: since
        in: query
        required: false
        description: 'Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept.'
        schema:
          type: string
      - name: until
        in: query
        required: false
        description: 'Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept.'
        schema:
          type: string
      - name: max_pages
        in: query
        required: false
        description: 1 to 50 (default 1). Walk up to this many pages in one call and return the rows from all of them.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - name: max_age_s
        in: query
        required: false
        description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
        schema:
          type: integer
          minimum: 0
          maximum: 3600
      - name: cursor
        in: query
        required: false
        description: The `pagination.next_cursor` from the previous page, sent back unchanged. Omit it for the first page.
        schema:
          type: string
      - name: dry_run
        in: query
        required: false
        description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
        schema:
          type: string
          enum:
          - '1'
      x-credits: 10
      x-group: User
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope2'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/PostPage'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
      x-stability: stable
    servers:
    - url: https://api.insightsocial.app
  /v1/truthsocial/post:
    get:
      operationId: truthsocial_post
      summary: Post
      description: 'Returns one Truth Social post: text content, like count, retruth count, reply count, media attachments, author info, and creation timestamp.


        Use it when you have a single post URL; use user/posts to list an account''s recent truths.


        **10 credits** per call.'
      tags:
      - truthsocial
      parameters:
      - name: url
        in: query
        required: true
        description: Full URL of the Truth Social post
        schema:
          type: string
          example: https://truthsocial.com/@realDonaldTrump/posts/117400465758567373
      - name: max_age_s
        in: query
        required: false
        description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
        schema:
          type: integer
          minimum: 0
          maximum: 3600
      - name: dry_run
        in: query
        required: false
        description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
        schema:
          type: string
          enum:
          - '1'
      x-credits: 10
      x-group: Post
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope2'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/PostOne'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
      x-stability: stable
    servers:
    - url: https://api.insightsocial.app
components:
  schemas:
    Pagination:
      type: object
      properties:
        next_cursor:
          type:
          - string
          - 'null'
        has_more:
          type: boolean
        page_size:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        stopped_at:
          anyOf:
          - type: string
            enum:
            - since
            - known_id
            - end
          - type: 'null'
      required:
      - next_cursor
      - has_more
      - page_size
      additionalProperties: false
    ProfileOne:
      type: object
      properties:
        author:
          $ref: '#/components/schemas/Profile'
      required:
      - author
      additionalProperties: false
    Envelope2:
      type: object
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        schema_version:
          type: string
          const: '2'
        data: {}
        pagination:
          $ref: '#/components/schemas/Pagination'
        unavailable:
          type: array
          items:
            type: string
        credits_used:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        credits_remaining:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        request_id:
          type: string
        cached:
          type: boolean
        idempotent_replay:
          type: boolean
        charge_reason:
          type: string
        free_call:
          type: boolean
      required:
      - success
      - platform
      - endpoint
      - schema_version
      - data
      - unavailable
      - credits_used
      - credits_remaining
      - request_id
      - cached
      - idempotent_replay
      - charge_reason
      - free_call
      additionalProperties: false
    Author:
      type: object
      properties:
        id:
          anyOf:
          - type: string
            minLength: 1
            description: 'An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.'
          - type: 'null'
        username:
          type:
          - string
          - 'null'
        display_name:
          type:
          - string
          - 'null'
        avatar_url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        verified:
          type:
          - boolean
          - 'null'
      required:
      - id
      - username
      - display_name
      - avatar_url
      - verified
      additionalProperties: false
    PostPage:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              post:
                $ref: '#/components/schemas/Post'
            required:
            - post
            additionalProperties: false
        total:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        truncated:
          type:
          - boolean
          - 'null'
        ext:
          anyOf:
          - type: object
            propertyNames:
              type: string
              pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
            additionalProperties:
              $ref: '#/components/schemas/JsonValue'
          - type: 'null'
          description: Platform-specific fields, snake_case. The key list per platform is in the docs.
      required:
      - items
      - total
      - truncated
      additionalProperties: false
    JsonValue:
      description: Any JSON value.
    Post:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: 'An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.'
        url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        kind:
          anyOf:
          - type: string
            minLength: 1
            description: The format of the post. Format words only, never a platform name. short = short-form vertical video (a reel, a TikTok, a YouTube Short).
            x-extensible-enum:
            - text
            - image
            - carousel
            - video
            - short
            - live
            - article
            - link
          - type: 'null'
        content:
          type: object
          properties:
            text:
              type:
              - string
              - 'null'
            media_urls:
              anyOf:
              - type: array
                items:
                  type: string
                  minLength: 1
                  format: uri
              - type: 'null'
            thumbnail_url:
              anyOf:
              - type: string
                minLength: 1
                format: uri
              - type: 'null'
            duration_seconds:
              anyOf:
              - type: number
                minimum: 0
              - type: 'null'
          required:
          - text
          - media_urls
          - thumbnail_url
          - duration_seconds
          additionalProperties: false
        author:
          $ref: '#/components/schemas/Author'
        engagement:
          type: object
          properties:
            views:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
            likes:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
            comments:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
            shares:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
            saves:
              anyOf:
              - type: integer
                minimum: 0
                maximum: 9007199254740991
              - type: 'null'
              description: A count. null when the platform does not expose it; 0 only when it is really zero.
          required:
          - views
          - likes
          - comments
          - shares
          - saves
          additionalProperties: false
        flags:
          type: object
          properties:
            nsfw:
              type:
              - boolean
              - 'null'
            spoiler:
              type:
              - boolean
              - 'null'
            pinned:
              type:
              - boolean
              - 'null'
            deleted:
              type: boolean
            likes_hidden:
              type:
              - boolean
              - 'null'
            comments_hidden:
              type:
              - boolean
              - 'null'
            shares_hidden:
              type:
              - boolean
              - 'null'
            views_hidden:
              type:
              - boolean
              - 'null'
            saves_hidden:
              type:
              - boolean
              - 'null'
          required:
          - nsfw
          - spoiler
          - pinned
          - deleted
          - likes_hidden
          - comments_hidden
          - shares_hidden
          - views_hidden
          - saves_hidden
          additionalProperties: false
        published_at:
          anyOf:
          - type: string
            format: date-time
            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            description: ISO-8601 timestamp in UTC, ending in Z.
          - type: 'null'
        language:
          anyOf:
          - type: string
            minLength: 2
            description: The content's language as the platform states it, e.g. en, pt-BR. Detected languages come later (§7.1).
          - type: 'null'
        ext:
          anyOf:
          - type: object
            propertyNames:
              type: string
              pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
            additionalProperties:
              $ref: '#/components/schemas/JsonValue'
          - type: 'null'
          description: Platform-specific fields, snake_case. The key list per platform is in the docs.
      required:
      - id
      - url
      - kind
      - content
      - author
      - engagement
      - flags
      - published_at
      - language
      - ext
      additionalProperties: false
    Error:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
            param:
              type: string
            top_up_url:
              type: string
          required:
          - type
          - message
          additionalProperties: false
        request_id:
          type: string
        credits_used:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        credits_remaining:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
      required:
      - success
      - error
      - request_id
      - credits_used
      - credits_remaining
      additionalProperties: false
    PostOne:
      type: object
      properties:
        post:
          $ref: '#/components/schemas/Post'
      required:
      - post
      additionalProperties: false
    Profile:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: 'An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.'
        username:
          type:
          - string
          - 'null'
        display_name:
          type:
          - string
          - 'null'
        avatar_url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        bio:
          type:
          - string
          - 'null'
        verified:
          type:
          - boolean
          - 'null'
        followers:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        followers_approximate:
          type:
          - boolean
          - 'null'
        following:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        posts_count:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        likes_count:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: A count. null when the platform does not expose it; 0 only when it is really zero.
        url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        location:
          type:
          - string
          - 'null'
        external_url:
          anyOf:
          - type: string
            minLength: 1
            format: uri
          - type: 'null'
        private:
          type:
          - boolean
          - 'null'
        joined_at:
          anyOf:
          - type: string
            format: date-time
            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            description: ISO-8601 timestamp in UTC, ending in Z.
          - type: 'null'
        last_post_at:
          anyOf:
          - type: string
            format: date-time
            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            description: ISO-8601 timestamp in UTC, ending in Z.
          - type: 'null'
        ext:
          anyOf:
          - type: object
            propertyNames:
              type: string
              pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
            additionalProperties:
              $ref: '#/components/schemas/JsonValue'
          - type: 'null'
          description: Platform-specific fields, snake_case. The key list per platform is in the docs.
      required:
      - id
      - username
      - display_name
      - avatar_url
      - bio
      - verified
      - followers
      - followers_approximate
      - following
      - posts_count
      - likes_count
      - url
      - location
      - external_url
      - private
      - joined_at
      - last_post_at
      - ext
      additionalProperties: false
  responses:
    Error:
      description: See [Error handling](https://www.insightsocial.app/docs/errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              type: INSUFFICIENT_CREDITS
              message: 'This call needs up to 340 credits and 120 remain. Add credits: https://www.insightsocial.app/api/top-up?need=220&u=6f1c2b7e-0d4a-4c8e-9b21-3a5f7d9e1c40&via=api_402'
              top_up_url: https://www.insightsocial.app/api/top-up?need=220&u=6f1c2b7e-0d4a-4c8e-9b21-3a5f7d9e1c40&via=api_402
            request_id: req_1a2b3c4d5e6f
            credits_used: 0
            credits_remaining: 120
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your key from the dashboard. It starts with `isk_`.
x-refined-from:
- openapi.json
- insightsocial-app-openapi.json
x-provenance:
  method: harvested
  publisher: InsightSocial
  source: https://api.insightsocial.app/v1/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)