- name: Bridge
  group: communities
  description: |
    Presents data interpreted by the hivemind database as JSON-RPC.
    
    Also see: [Communities Broadcast Ops]({{ '/apidefinitions/#apidefinitions-broadcast-ops-communities' | relative_url }})
  methods:
  - api_method: bridge.get_ranked_posts
    purpose: |
      Get ranked posts.
      
      Supported values for `sort`:
        * `trending`
        * `hot`
        * `created`
        * `promoted`
        * `payout`
        * `payout_comments`
        * `muted`
        
      The value for `tag` can be any valid tag.
      
      The value for `observer` can be any valid account or empty string.
    parameter_json: '{"sort":"","tag":"","observer":""}'
    expected_response_json: |
      [
        {
           "post_id":12345678,
           "author":"alice",
           "permlink":"that-march-hare",
           "category":"wonderland",
           "title":"That March Hare",
           "body":"I think he went mad.",
           "json_metadata":{"tags":["wonderland"], "app":"hiveblog/0.1"},
           "created":"2019-12-05T16:29:12",
           "updated":"2019-12-05T16:29:12",
           "depth":0,
           "children":0,
           "net_rshares":1539574839484,
           "is_paidout":false,
           "payout_at":"2019-12-12T16:29:12",
           "payout":0.286,
           "pending_payout_value":"0.286 HBD",
           "author_payout_value":"0.000 HBD",
           "curator_payout_value":"0.000 HBD",
           "promoted":"0.000 HBD",
           "replies":[],
           "active_votes":[
              {"voter":"bob", "rshares":"67759296290"}
           ],
           "author_reputation":47.15,
           "stats":{
              "hide":false,
              "gray":false,
              "total_votes":12,
              "flag_weight":0
           },
           "beneficiaries":[],
           "max_accepted_payout":"1000000.000 HBD",
           "percent_hbd":10000,
           "url":"/wonderland/@alice/that-march-hare",
           "blacklists":[]
        }
      ]
    curl_examples:
    - '{"jsonrpc":"2.0", "method":"bridge.get_ranked_posts", "params":{"sort":"trending","tag":"","observer":"alice"}, "id":1}'
  - api_method: bridge.account_notifications
    purpose: |
      Account notifications.
      
      Supported values for `type`:
        * `new_community` - a new community was created
        * `set_role` - mod/admin adds a role to an account
        * `set_props` - properties set for a community
        * `set_label` - a title/badge/label has been set for an account
        * `mute_post` - a post has been muted, with a reason
        * `unmute_post` - a post has been unmuted, with a reason
        * `pin_post` - a post has been pinned
        * `unpin_post` - a post has been unpinned
        * `flag_post` - a post has been flagged by a member, with a reason
        * `error` - provides feedback to developers for ops that cannot be interpreted
        * `subscribe` - an account has subscribed to a community
        * `reply` - a post has been replied to
        * `reblog` - a post has been reblogged/resteemed
        * `follow` - an account has followed another account
        * `mention` - author mentions an account
        * `vote` - voter votes for an author
      
      The `score` value is based on the originating account's rank.
    parameter_json: '{"account":"alice","limit":100}'
    expected_response_json: |
      [{
        "id": 3629306,
        "type": "vote",
        "score": 25,
        "date": "2019-11-20T07:48:06",
        "msg": "@bob voted on your post ($0.013)",
        "url": "@alice/a-post-by-alice"
      }]
    curl_examples:
    - '{"jsonrpc":"2.0", "method":"bridge.account_notifications", "params":{"account":"alice","limit":100}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_account_notifications)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.does_user_follow_any_lists
    purpose: Checks if a given observer follows any blacklists or mute lists.
    parameter_json: '{"observer":"alice"}'
    expected_response_json: |
      false
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.does_user_follow_any_lists", "params":{"observer":"alice"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_does_user_follow_any_lists)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.get_account_posts
    purpose: |
      Lists posts related to a given account.
      
      * `sort` - Supported values:
        * `blog` - top posts authored by given account (excluding posts to communities - unless explicitely reblogged) plus reblogs ranked by creation/reblog time
        * `feed` - top posts from blogs of accounts that given account is following ranked by creation/reblog time, not older than last month
        * `posts` - op posts authored by given account, newer first   comments - replies authored by given account, newer first
        * `replies` - replies to posts of given account, newer first
        * `payout` - all posts authored by given account that were not yet cashed out
      * `account`: account name, points to valid account
      * `start_author`: author account name, if passed must be passed with `start_permlink` [optional]
      * `start_permlink`: post permlink of given author, point to valid post, paging mechanism [optional]
      * `limit`: if omitted the server will use the default value of 20 [optional]
      * `observer`: ignored for `blog`, feed and `replies`, otherwise when passed has to point to valid account used to fill blacklist stats and mark posts of authors blacklisted by observer, at this time ignored [optional] 
    parameter_json: {"sort":"blog", "account": "alice", "limit": 1}
    expected_response_json: |
      [
        {
          "post_id": 101867403,
          "author": "hiveio",
          "permlink": "around-the-hive-reflections",
          "category": "hiveecosystem",
          "title": "Around the Hive: Reflections",
          "body": "It's been a busy year so far for developers on Hive. Layer 2 solutions are in progress, key optimization is an ongoing priority ...",
          "json_metadata": {
            "tags": [
              "hiveecosystem"
            ],
            "users": [
              "blocktrades",
              "howo"
            ],
            "image": [
              "https://images.hive.blog/768x0/https://files.peakd.com/file/peakd-hive/hiveio/pKjrNcbK-Hive-Wallpaper-1920x1080.png",
              "https://images.hive.blog/DQmR3iwCn9yvwXDXfuNjmMX6FrjAvFfYQWgA4QRckpens1j/hive%20dividers-02.png"
            ],
            "links": [
              "https://gitlab.syncad.com/hive/hive-whitepaper/-/blob/master/technical-vision/infographic.pdf"
            ],
            "app": "hiveblog/0.1",
            "format": "markdown",
            "description": "The strength of Hive lies in our decentralization."
          },
          "created": "2021-02-14T08:16:03",
          "updated": "2021-02-14T08:16:03",
          "depth": 0,
          "children": 15,
          "net_rshares": 93531156115025,
          "is_paidout": true,
          "payout_at": "2021-02-21T08:16:03",
          "payout": 0,
          "pending_payout_value": "0.000 HBD",
          "author_payout_value": "0.000 HBD",
          "curator_payout_value": "0.000 HBD",
          "promoted": "0.000 HBD",
          "replies": [],
          "author_reputation": 69.29,
          "stats": {
            "hide": false,
            "gray": false,
            "total_votes": 129,
            "flag_weight": 0
          },
          "url": "/hiveecosystem/@hiveio/around-the-hive-reflections",
          "beneficiaries": [],
          "max_accepted_payout": "0.000 HBD",
          "percent_hbd": 10000,
          "active_votes": [],
          "blacklists": []
        }
      ]
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.get_account_posts", "params":{"sort":"blog", "account": "alice", "limit": 1}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_get_account_posts)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.get_community_context
    purpose: Gets the role, subscription status, and title for a given account in a given community.
    parameter_json: {"name": "hive-111111", "account": "therealwolf"}
    expected_response_json: {"role":"admin","subscribed":true,"title":"Witness: @therealwolf"}
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.get_community_context", "params":{"name": "hive-111111", "account": "therealwolf"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_get_community_context)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.get_discussion
    purpose: Gives a flattened discussion tree starting at given post.
    parameter_json: {"author": "hiveio", "permlink": "around-the-hive-reflections", "observer": "alice"}
    expected_response_json: |
      {"hiveio/around-the-hive-reflections":
        {
          "post_id": 101867403,
          "author": "hiveio",
          "permlink": "around-the-hive-reflections",
          "category": "hiveecosystem",
          "title": "Around the Hive: Reflections",
          "body": "It's been a busy year so far for developers on Hive. Layer 2 solutions are in progress, key optimization is an ongoing priority ...",
          "json_metadata": {
            "tags": [
              "hiveecosystem"
            ],
            "users": [
              "blocktrades",
              "howo"
            ],
            "image": [
              "https://images.hive.blog/768x0/https://files.peakd.com/file/peakd-hive/hiveio/pKjrNcbK-Hive-Wallpaper-1920x1080.png",
              "https://images.hive.blog/DQmR3iwCn9yvwXDXfuNjmMX6FrjAvFfYQWgA4QRckpens1j/hive%20dividers-02.png"
            ],
            "links": [
              "https://gitlab.syncad.com/hive/hive-whitepaper/-/blob/master/technical-vision/infographic.pdf"
            ],
            "app": "hiveblog/0.1",
            "format": "markdown",
            "description": "The strength of Hive lies in our decentralization."
          },
          "created": "2021-02-14T08:16:03",
          "updated": "2021-02-14T08:16:03",
          "depth": 0,
          "children": 15,
          "net_rshares": 93531156115025,
          "is_paidout": true,
          "payout_at": "2021-02-21T08:16:03",
          "payout": 0,
          "pending_payout_value": "0.000 HBD",
          "author_payout_value": "0.000 HBD",
          "curator_payout_value": "0.000 HBD",
          "promoted": "0.000 HBD",
          "replies": [],
          "author_reputation": 69.29,
          "stats": {
            "hide": false,
            "gray": false,
            "total_votes": 129,
            "flag_weight": 0
          },
          "url": "/hiveecosystem/@hiveio/around-the-hive-reflections",
          "beneficiaries": [],
          "max_accepted_payout": "0.000 HBD",
          "percent_hbd": 10000,
          "active_votes": [],
          "blacklists": []
        }
      }
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.get_discussion", "params":{"author": "hiveio", "permlink": "around-the-hive-reflections", "observer": "alice"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_get_discussion)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.get_follow_list
    purpose: |
      Returns blacklisted/muted accounts or list of blacklists/mute lists followed by a given observer.
      
      * `observer` - valid account
      * `follow_type` - Supported values:
        * `follow_blacklist`
        * `follow_muted`
    parameter_json: {"observer": "blocktrades", "follow_type": "follow_blacklist"}
    expected_response_json: [{"name":"hive.blog","blacklist_description":"","muted_list_description":""}]
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.get_follow_list", "params":{"observer": "blocktrades", "follow_type": "follow_blacklist"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_get_follow_list)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.get_profile
    purpose: |
      Gets profile
      
      * `account` - valid account
      * `observer` - valid account [optional]
    parameter_json: {"account": "alice", "observer": "bob"}
    expected_response_json: |
      {
          "id": 241,
          "name": "alice",
          "created": "2016-03-25T15:09:27",
          "active": "2016-04-29T22:28:00",
          "post_count": 0,
          "reputation": 25,
          "blacklists": [],
          "stats": {
            "rank": 0,
            "following": 0,
            "followers": 431
          },
          "metadata": {
            "profile": {
              "name": "",
              "about": "",
              "website": "",
              "location": "",
              "cover_image": "",
              "profile_image": "",
              "blacklist_description": "",
              "muted_list_description": ""
            }
          },
          "context": {
            "followed": false
          }
        }
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.get_profile", "params":{"account": "alice", "observer": "bob"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_get_profile)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.list_communities
    purpose: |
      Gets community
      
      * `last` - name of community; paging mechanism [optional]
      * `limit` - limit number of listed communities, default: `100` [optional]
      * `query` - filters against `title` and `about` community fields [optional]
      * `sort` - default: `rank` [optional]
        * `rank` - sort by community rank
        * `new` - sort by newest community
        * `subs` - sort by subscriptions
      * `observer` - a valid account [optional]
    parameter_json: {"limit": 1, "query": "wall street bets"}
    expected_response_json: |
      [
        {
          "id": 1432978,
          "name": "hive-103566",
          "title": "Wall Street Bets",
          "about": "Wall Street Bets - In Case Reddit Shuts Down.",
          "lang": "en",
          "type_id": 1,
          "is_nsfw": false,
          "subscribers": 6,
          "sum_pending": 0,
          "num_pending": 0,
          "num_authors": 0,
          "created_at": "2021-01-28 18:34:09",
          "avatar_url": "",
          "context": {},
          "admins": [
            "spitr"
          ]
        }
      ]
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.list_communities", "params":{"limit": 1, "query": "wall street bets"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_list_communities)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.list_pop_communities
    purpose: |
      Gets a list of popular communities.
      
      * `limit` - limit number of listed communities, default: `25` [optional]
    parameter_json: {"limit": 10}
    expected_response_json:
      [
        ["hive-167922", "LeoFinance"],
        ["hive-194913", "Photography Lovers"],
        ["hive-148441", "GEMS"],
        ["hive-196037", "DTube"],
        ["hive-196708", "Hive Pets"],
        ["hive-120586", "Foodies Bee Hive"],
        ["hive-140217", "Hive Gaming"],
        ["hive-174578", "OCD"],
        ["hive-129496", "Nerday"],
        ["hive-193816", "Music"]
      ]
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.list_pop_communities", "params":{"limit": 10}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_list_pop_communities)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.list_subscribers
    purpose: |
      Gets a list of subscribers for a given community.
      
      * `community` - community category name
      * `last` - name of subscriber; paging mechanism [optional]
      * `limit` - limit number of listed subscribers, default: `100` [optional]
    parameter_json: {"community": "hive-111111", "limit": 10}
    expected_response_json: |
      [
        ["gatticus", "guest", null, "2021-02-18 13:15:42"],
        ["thewarkettle", "guest", null, "2021-02-15 22:04:36"],
        ["darkflame", "guest", null, "2021-02-14 00:30:12"],
        ["oiuygtfrd76543", "guest", null, "2021-02-01 19:35:03"],
        ["bhattg", "guest", null, "2021-02-01 18:39:06"],
        ["elenahornfilm", "guest", null, "2021-02-01 09:19:54"],
        ["mrhappypants", "guest", null, "2021-02-01 01:03:48"],
        ["petrahaller", "guest", null, "2021-02-01 00:08:09"],
        ["hgregoria", "guest", null, "2021-01-29 18:46:12"],
        ["theblockabout", "guest", null, "2021-01-29 15:21:48"]
      ]
    curl_examples:
      - '{"jsonrpc":"2.0", "method":"bridge.list_subscribers", "params":{"community": "hive-111111", "limit": 10}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_list_subscribers)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.list_community_roles
    purpose: |
      List community roles and labels for each account in the community.
      
      * `community` - community category name
      * `last` - name of subscriber; paging mechanism [optional]
      * `limit` - limit number of listed subscribers, default: `100` [optional]
    parameter_json: '{"community":"hive-123456"}'
    expected_response_json: |
      [
        ["hive-123456", "owner", ""],
        ["alice", "admin", "Miss"]
      ]
    curl_examples:
    - '{"jsonrpc":"2.0", "method":"bridge.list_community_roles", "params":{"community":"hive-123456"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_list_community_roles)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.list_all_subscriptions
    purpose: |
      List all subscriptions, titles, and roles to a community for an account.
      
      * `account`: account name, points to valid account
    parameter_json: '{"account":"alice"}'
    expected_response_json: |
      [
        ["hive-123456", "Wonderland", "guest", ""],
        ["hive-654321", "Tulgey Wood", "admin", "Mrs. Vex"]
      ]
    curl_examples:
    - '{"jsonrpc":"2.0", "method":"bridge.list_all_subscriptions", "params":{"account":"alice"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_list_all_subscriptions)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
  - api_method: bridge.get_community
    purpose: |
      Get community details.
      
      * `name` - community category name
      * `observer` - valid account [optional]
    parameter_json: '{"name":"hive-123456","observer":"alice"}'
    expected_response_json: 
      {
        "id": 1332149,
        "name": "hive-123456",
        "title": "@hive-123456",
        "about": "Wonderland",
        "lang": "en",
        "type_id": 1,
        "is_nsfw": false,
        "subscribers": 0,
        "sum_pending": 0,
        "num_pending": 0,
        "num_authors": 0,
        "created_at": "2019-10-27 08:28:54",
        "context": {
          "role": "admin",
          "title": "Miss",
          "subscribed": true
        },
        "avatar_url": "",
        "description": "",
        "flag_text": "",
        "settings": {},
        "team": [
          ["hive-123456", "owner", ""],
          ["alice", "admin", "Miss"]
        ]
    }
    curl_examples:
    - '{"jsonrpc":"2.0", "method":"bridge.get_community", "params":{"name":"hive-123456","observer":"alice"}, "id":1}'
    client_docs:
      - '[openApi](https://gitlab.syncad.com/hive/hivemind/-/blob/pczempiel_openapi_bridge/openApi/client/docs/DefaultApi.md#bridge_get_community)'
      - '[hive-ruby](https://www.rubydoc.info/gems/hive-ruby/Hive/Bridge)'
