posts_api

Module Group: Posts
Parsing Order: 210
Database Size: 124.417 GB

The posts_api is the primary module for accessing post and comment data on the Steem blockchain. It provides comprehensive access to post content, metadata, votes, payouts, beneficiaries, and replies.

Configuration

{
   "id": "posts_api",
   "group_id": "posts",
   "parsing_order": 210,
   "required_modules": ["chain_api"],
   "optional_modules": [
      "post_resteems_api",
      "post_votes_api",
      "accounts_api",
      "communities_api",
      "followers_api"
   ],
   "referenced_modules": ["feeds_api", "steem_requests_api"],
   "data_source_contents": ["posts"],
   "parse_reversible": true,
   "parsed_ops": ["comment_options"],
   "available_events": ["onSyncPost"],
   "event_handlers": [
      "chain_api.onCreatePost",
      "chain_api.onUpdatePost",
      "chain_api.onRemovePost",
      "chain_api.onVote",
      "chain_api.onAuthorReward"
   ]
}

Database Info

{
   "name": "posts_api",
   "size": "124.417 GB",
   "page_size": "4096 Bytes",
   "type": "SQLITE",
   "journal_mode": "WAL",
   "busy_timeout": 10000,
   "log_level": "INFO"
}

Endpoints Overview

Category Endpoint Description
Config getConfig Module configuration
Post Data By Link
getPost Get post by author/permlink
getPostReplies Get replies to a post
getPostWithReplies Get post with all replies
getBeneficiaries Get post beneficiaries
getPayout Get payout information
getVotes Get all votes on a post
Post Data By Id
getPostById Get post by link ID
getPostRepliesById Get replies by link ID
getPostWithRepliesById Get post with replies by ID
getBeneficiariesById Get beneficiaries by ID
getPayoutById Get payout by ID
getVotesById Get votes by ID
Other
getRootPostsByAuthor Get author's root posts
getPostsForSync Internal sync endpoint

Common Parameters

withVotes Parameter

Include vote data with the post.

Value Description
true or 1 Include votes
false or 0 Exclude votes (default)

observer Parameter

Account name to check observer-specific data (follows, votes, etc.)

Value Description
true or 1 Enable observer fields
false or 0 Disable observer fields

fields Parameter

Comma-separated list of fields to include in the response. Available fields:

link_id, link_status, author_reputation, author_status, author_role, author_title,
author, permlink, parent_author, parent_permlink, parent_link_id, root_author,
root_permlink, root_title, beneficiaries, created, last_update, last_sync,
cashout_time, payout, total_payout_value, curator_payout_value, pending_payout_value,
net_rshares, total_vote_weight, max_accepted_payout, percent_steem_dollars,
allow_curation_rewards, allow_votes, allow_replies, depth, children, resteem_count,
upvote_count, downvote_count, word_count, observer_follows_author, observer_ignores_author,
observer_resteem, observer_role, observer_title, observer_vote, observer_vote_percent,
observer_vote_rshares, is_author_muted, is_muted, is_pinned, category, community,
json_images, json_metadata, title, body

Endpoints

getConfig

Returns this module's active configuration.

Endpoint

/posts_api/getConfig

Example Request

https://sds.steemworld.org/posts_api/getConfig

Result: JSON Object containing the module configuration

Post Data By Link

getPost

Returns the post data for the given author and permlink.

Endpoint

/posts_api/getPost/:author/:permlink/:withVotes?/:observer?/:fields?

Parameters

Name Type Optional Description
:author string No Post author username
:permlink string No Post permlink
:withVotes boolean Yes Include vote data
:observer string Yes Observer account for personalized data
:fields string Yes Comma-separated list of fields to return

Example Request

https://sds.steemworld.org/posts_api/getPost/steemit/firstpost

Example Response (Steem's First Post):

{
   "code": 0,
   "result": {
      "link_id": 1,
      "link_status": 0,
      "author_reputation": 35.007,
      "author": "steemit",
      "permlink": "firstpost",
      "parent_author": "",
      "parent_permlink": "meta",
      "created": 1459362618,
      "last_update": 1459362618,
      "payout": 1.698,
      "total_payout_value": 0.942,
      "curator_payout_value": 0.756,
      "pending_payout_value": 0,
      "depth": 0,
      "children": 441,
      "resteem_count": 22,
      "upvote_count": 578,
      "downvote_count": 14,
      "word_count": 42,
      "category": "meta",
      "title": "Welcome to Steem!",
      "body": "Steemit is a social media platform where anyone can earn STEEM points by posting...",
      "beneficiaries": []
   }
}

getPostReplies

Returns all replies (comments) to the post with the given author and permlink.

Endpoint

/posts_api/getPostReplies/:author/:permlink/:withVotes?/:observer?/:fields?

Parameters

Name Type Optional Description
:author string No Post author username
:permlink string No Post permlink
:withVotes boolean Yes Include vote data
:observer string Yes Observer account
:fields string Yes Fields to return

Example Request

https://sds.steemworld.org/posts_api/getPostReplies/steemit/firstpost

Result: JSON Object containing array of reply posts

getPostWithReplies

Returns both the post data and all its replies in a single request.

Endpoint

/posts_api/getPostWithReplies/:author/:permlink/:withVotes?/:observer?/:fields?

Parameters

Name Type Optional Description
:author string No Post author username
:permlink string No Post permlink
:withVotes boolean Yes Include vote data
:observer string Yes Observer account
:fields string Yes Fields to return

Example Request

https://sds.steemworld.org/posts_api/getPostWithReplies/bestmalik/re-steemit-firstpost-20160726t035722561z

Result: JSON Object containing post and nested replies

getBeneficiaries

Returns all beneficiaries set for a post (accounts that receive a portion of the rewards).

Endpoint

/posts_api/getBeneficiaries/:author/:permlink

Parameters

Name Type Optional Description
:author string No Post author username
:permlink string No Post permlink

Example Request

https://sds.steemworld.org/posts_api/getBeneficiaries/steemit/firstpost

Example Response (no beneficiaries):

{
   "code": 0,
   "result": {
      "cols": {},
      "rows": []
   }
}

Result: JSON Object containing beneficiary accounts and their percentage shares

getPayout

Returns the payout data for a post including author rewards, curator rewards, and pending payouts.

Endpoint

/posts_api/getPayout/:author/:permlink/:withVotes?/:withBenefs?

Parameters

Name Type Optional Description
:author string No Post author username
:permlink string No Post permlink
:withVotes boolean Yes Include vote data
:withBenefs boolean Yes Include beneficiary data

Example Request

https://sds.steemworld.org/posts_api/getPayout/steemit/firstpost

Example Response:

{
   "code": 0,
   "result": {
      "created": 1459362618,
      "last_update": 1459362618,
      "payout": 1.698,
      "total_payout_value": 0.942,
      "curator_payout_value": 0.756,
      "pending_payout_value": 0,
      "net_rshares": 830053779138,
      "total_vote_weight": 0,
      "max_accepted_payout": 1,
      "percent_steem_dollars": 10000,
      "allow_curation_rewards": 1
   }
}

getVotes

Returns all votes on a post.

Endpoint

/posts_api/getVotes/:author/:permlink

Parameters

Name Type Optional Description
:author string No Post author username
:permlink string No Post permlink

Example Request

https://sds.steemworld.org/posts_api/getVotes/steemit/firstpost

Example Response:

{
   "code": 0,
   "result": {
      "cols": {"voter": 0, "time": 1, "percent": 2, "weight": 3, "rshares": 4},
      "rows": [
         ["dantheman", 1460056536, 100, 32866333630, 375241],
         ["mr11acdee", 1459970943, 10000, 876019385955, 886132],
         ["liondani", 1465428714, 10000, 7704121196, 551390835500]
      ]
   }
}

Vote Columns:

Column Description
voter Account that voted
time Unix timestamp of vote
percent Vote percentage (10000 = 100%)
weight Vote weight
rshares Reward shares

Post Data By Id

These endpoints function identically to the "By Link" versions but use the internal link_id instead of author/permlink.

getPostById

Returns post data for the given link ID.

Endpoint

/posts_api/getPostById/:linkId/:withVotes?/:observer?/:fields?

Parameters

Name Type Optional Description
:linkId int No Internal post link ID
:withVotes boolean Yes Include vote data
:observer string Yes Observer account
:fields string Yes Fields to return

Example Request

https://sds.steemworld.org/posts_api/getPostById/1

Note: Link ID 1 refers to Steem's first post (steemit/firstpost)

getPostRepliesById

Returns all replies of the post with the given link ID.

Endpoint

/posts_api/getPostRepliesById/:linkId/:withVotes?/:observer?/:fields?

Example Request

https://sds.steemworld.org/posts_api/getPostRepliesById/1

getPostWithRepliesById

Returns the post data and all replies for the given link ID.

Endpoint

/posts_api/getPostWithRepliesById/:linkId/:withVotes?/:observer?/:fields?

Example Request

https://sds.steemworld.org/posts_api/getPostWithRepliesById/264480

getBeneficiariesById

Returns all beneficiaries of the post with the given link ID.

Endpoint

/posts_api/getBeneficiariesById/:linkId

Example Request

https://sds.steemworld.org/posts_api/getBeneficiariesById/1

getPayoutById

Returns payout data for the post with the given link ID.

Endpoint

/posts_api/getPayoutById/:linkId/:withVotes?/:withBenefs?

Parameters

Name Type Optional Description
:linkId int No Internal post link ID
:withVotes boolean Yes Include vote data
:withBenefs boolean Yes Include beneficiary data

Example Request

https://sds.steemworld.org/posts_api/getPayoutById/1

getVotesById

Returns all votes of the post with the given link ID.

Endpoint

/posts_api/getVotesById/:linkId

Example Request

https://sds.steemworld.org/posts_api/getVotesById/1

Other Endpoints

getRootPostsByAuthor

Returns an author's root posts (not replies) ordered by creation time descending.

Endpoint

/posts_api/getRootPostsByAuthor/:author/:withVotes?/:observer?/:fields?/:limit?/:offset?

Parameters

Name Type Optional Default Description
:author string No - Account username
:withVotes boolean Yes false Include vote data
:observer string Yes - Observer account
:fields string Yes all Fields to return
:limit int Yes 20 Maximum results (max: 100)
:offset int Yes 0 Result offset

Max. Limit: 100

Example Request

https://sds.steemworld.org/posts_api/getRootPostsByAuthor/steemit

Result: JSON Object containing array of the author's root posts

getPostsForSync

Internally used for fast post data synchronization between SDS instances.

Endpoint

/posts_api/getPostsForSync/:query

Note: This is an internal endpoint used by SDS infrastructure.

Result: JSON Array

Response Field Definitions

Post Fields

Field Type Description
link_id int Unique internal post ID
link_status int Post status (0 = active)
author_reputation float Author's reputation score
author_status int Author account status
author_role string Author's role in community
author_title string Author's title in community
author string Post author username
permlink string Post permlink
parent_author string Parent post author (empty for root posts)
parent_permlink string Parent post permlink or category
parent_link_id int Parent post link ID
root_author string Root post author
root_permlink string Root post permlink
root_title string Root post title
beneficiaries array Beneficiary accounts and percentages
created int Unix timestamp of creation
last_update int Unix timestamp of last edit
last_sync int Unix timestamp of last sync
cashout_time int Payout time (0 = already paid)
payout float Total payout value
total_payout_value float Author payout
curator_payout_value float Curator payout
pending_payout_value float Pending payout (before cashout)
net_rshares int Net reward shares
total_vote_weight int Total weight of votes
max_accepted_payout int Maximum accepted payout
percent_steem_dollars int SBD percentage (10000 = 100%)
allow_curation_rewards int 1 = enabled, 0 = disabled
allow_votes int 1 = enabled, 0 = disabled
allow_replies int 1 = enabled, 0 = disabled
depth int Reply depth (0 = root post)
children int Number of replies
resteem_count int Number of resteems
upvote_count int Number of upvotes
downvote_count int Number of downvotes
word_count int Body word count
is_author_muted int 1 = author muted in community
is_muted int 1 = post muted in community
is_pinned int 1 = post pinned in community
category string Post category/tag
community string Community name if posted to community
json_images string JSON array of image URLs
json_metadata string Post JSON metadata
title string Post title
body string Post body content (Markdown)

Observer Fields

These fields are populated when an observer account is specified:

Field Description
observer_follows_author Observer follows the author
observer_ignores_author Observer muted the author
observer_resteem Observer resteemed the post
observer_role Observer's role in community
observer_title Observer's title in community
observer_vote Observer voted on post
observer_vote_percent Observer's vote percentage
observer_vote_rshares Observer's vote rshares

Use Cases

  1. Post display - Fetch complete post data for rendering
  2. Comment threads - Get post with all nested replies
  3. Payout analysis - Track author and curator rewards
  4. Vote analysis - Analyze voting patterns on posts
  5. Author blog - List all posts by an author
  6. Beneficiary tracking - See reward splits
  7. Community content - Filter posts by community
  8. Content moderation - Check muted/pinned status

Notes

Back to Main Index