Talks API ========= .. contents:: :depth: 2 Runtime ####### Get Talk -------- .. code:: GET /core/v1/talks/?include=&mode=&forced_ids= =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``talk_id`` String Required ``mode`` String Required, values: public, review, manage ``inclusions`` Comma-separated list of Strings Optional, values: featured-messages, top-level-messages, replies, authors, admins, reactions, bans ``forced_ids`` Comma-separated list of Strings Optional, values: message IDs ``order`` String Required when messages/replies included, values: best, newest, oldest ``limit`` Integer Required when messages/replies included =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "talk": { "id": "my-talk-id", "counts": { "messages": { "public": 14, "featured": 7 } } }, "messages": { "forced": [ { ... }, // See "Create Message" endpoint ... ], "featured": [ { ... }, // See "Create Message" endpoint ... ], "top-level": [ { ... }, // See "Create Message" endpoint ... ] }, "replies": [ { ... }, // See "Create Message" endpoint ... ], "authors": [ { ... }, // See "Create Message" endpoint ... ], "reactions": [ { ... }, // See "React to a message" endpoint ... ], "admins": [ ... // See "Create Message" endpoint ], "bans": [ { ... }, // See "Ban an author" endpoint ... ] } Get Messages ------------ .. code:: GET /core/v1/talks//messages?order=&limit=&offset=&excluded_ids=&mode= =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``talk_id`` String Required ``mode`` String Required, values: public, review, manage ``order`` String Required, values: best, newest, oldest ``limit`` Integer Required ``offset`` Integer Required ``excluded_ids`` Comma-separated list of Strings Optional, values: message IDs =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "talk": { "id": "my-talk-id", "counts": { "messages": { "public": 15, "featured": 3 } } }, "messages": [ { ... }, // See "Create Message" endpoint ... ], "authors": [ { ... }, // See "Create Message" endpoint ... ], "reactions": [ { ... }, // See "React to a message" endpoint ... ], "admins": [ ... // See "Create Message" endpoint ], "bans": [ { ... }, // See "Ban an author" endpoint ... ] } Create Message -------------- .. code:: POST /core/v1/talks//messages { "text": "" } =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``talk_id`` String Required ``text`` String Required =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "message": { "id": "5b27aa52bd96bc0e3ec0eaf9", "html": "

Hey hey!

", "status": "proposed", "talk_id": "post:123123:comments", "author_id": 321321, // Corresponds to `author.owner_id` "created_ts": 1435145454, "updated_ts": 1435145454, "parents": [], "counts": { "replies": { "total": 0, "direct": 0, "public": { "total": 0, "direct": 0 } } } }, "authors": [ { "id": 123123, "path": "community/trump/" "title": "Donald Trump", "image": "https://assets.rbl.ms/10301091/210x.png", "about": "A short bio here...", "rating": 3, "owner_id": 321321 } ], "reactions": [ { ... }, // See "React to a message" endpoint ... ], "admins": [ 111, 222, ... // corresponds to `message.author_id` ] } Get Message ----------- .. code:: GET /core/v1/talks//messages/ =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``talk_id`` String Required ``message_id`` String Required =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "message": { "id": "5b27aa52bd96bc0e3ec0eaf9", "html": "

Hey hey!

", "status": "proposed", "talk_id": "post:123123:comments", "author_id": 321321, // Corresponds to `author.owner_id` "created_ts": 1435145454, "updated_ts": 1435145454, "parents": [], "counts": { "replies": { "total": 0, "direct": 0, "public": { "total": 0, "direct": 0 } } } }, "authors": [ { ... }, // See "Create Message" endpoint ... ], "reactions": [ { ... }, // See "React to a message" endpoint ... ], "admins": [ ... // See "Create Message" endpoint ], } Update Message -------------- .. code:: POST /core/v1/talks//messages/ { "changes": [ {"status": ""}, {"text": ""} ] } =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``talk_id`` String Required ``message_id`` String Required ``text`` String Required for the change ``status`` String Required for the change, values: proposed, rejected, approved, featured =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "message": { "id": "5b27aa52bd96bc0e3ec0eaf9", "html": "This is new text", "status": "featured", "talk_id": "post:123123:comments", "author_id": 321321, // Corresponds to `author.owner_id` "created_ts": 1435145454, "updated_ts": 1435145454, "parents": [], "counts": { "replies": { "total": 0, "direct": 0, "public": { "total": 0, "direct": 0 } } } }, "authors": [ { ... }, // See "Create Message" endpoint ... ], "reactions": [ { ... }, // See "React to a message" endpoint ... ], "admins": [ ... // See "Create Message" endpoint ], } Get Message Replies ------------------- .. code:: GET /core/v1/talks//messages//replies?order=&limit=&offset=&excluded_ids=&mode= =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``talk_id`` String Required ``message_id`` String Required ``mode`` String Required, values: public, review, manage ``order`` String Required, values: best, newest, oldest ``limit`` Integer Required ``offset`` Integer Required ``excluded_ids`` Comma-separated list of Strings Optional, values: message IDs =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "message": { "id": "5b27aa52bd96bc0e8e5aed1f", "counts": { "replies": { "total": 1, "direct": 1, "public": { "total": 0, "direct": 0, } } } }, "replies": [ { ... }, // See "Create Message" endpoint ... ], "authors": [ { ... }, // See "Create Message" endpoint ... ], "reactions": [ { ... }, // See "React to a message" endpoint ... ], "admins": [ ... // See "Create Message" endpoint ], "bans": [ { ... }, // See "Ban an author" endpoint ... ] } Reply to Message ---------------- .. code:: POST /core/v1/talks//messages//replies { "text": "" } =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``talk_id`` String Required ``message_id`` String Required ``text`` String Required =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "message": { "id": "5b27aa52bd96bc0e3ec0eaf9", "html": "

Hey hey!

", "status": "proposed", "talk_id": "post:123123:comments", "author_id": 321321, // Corresponds to `author.owner_id` "created_ts": 1435145454, "updated_ts": 1435145454, "parents": ["5b27aa52bd96bc0e8e5aed1f"], "counts": { "replies": { "total": 0, "direct": 0, "public": { "total": 0, "direct": 0 } } } }, "authors": [ { ... }, // See "Create Message" endpoint ... ], "reactions": [ { ... }, // See "React to a message" endpoint ... ], "admins": [ ... // See "Create Message" endpoint ] } React on Message ---------------- .. code:: POST /core/v1/talks//messages//reactions { "reaction": "" } .. code:: DELETE /core/v1/talks//messages//reactions =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``talk_id`` String Required ``message_id`` String Required ``reaction`` String Required, values: like, dislike =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "message": { "id": "5b27aa52bd96bc0e3ec0eaf9", "html": "

Hey hey!

", "status": "proposed", "talk_id": "post:123123:comments", "author_id": 321321, // Corresponds to `author.owner_id` "created_ts": 1435145454, "updated_ts": 1435145454, "parents": ["5b27aa52bd96bc0e8e5aed1f"], "counts": { "replies": { "total": 0, "direct": 0, "public": { "total": 0, "direct": 0 } } } }, "authors": [ { ... }, // See "Create Message" endpoint ... ], "reactions": [ { "message_id": "5b27aa52bd96bc0e3ec0eaf9", "reaction": "like" // Alternatives: "dislike" } ], "admins": [ ... // See "Create Message" endpoint ] } Report Message -------------- .. code:: POST /core/v1/talks//messages//reports { "reason": "", "description": "" } =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``talk_id`` String Required ``message_id`` String Required ``reason`` String Required, values: spam, abuse, porno, violence, other ``description`` String Optional =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "report": { "reason": "other", // Alternatives: "spam", "abuse", "porno", "violence" "details": { # the content of `details` has no consistent structure "acting_user_id": 12312, "description": "some text here" }, "created_ts": 1435145454 } } Get Message Reports ------------------- .. code:: GET /core/v1/talks//messages//reports =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``talk_id`` String Required ``message_id`` String Required =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "report": { { ... }, // See "Report Message" endpoint ... } } Ban/Unban Author ---------------- .. code:: POST /core/v1/talks/bans { "author_id": "", "messages": "" } .. code:: DELETE /core/v1/talks/bans ======================= =============================== ===================== Parameter Type Description ======================= =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``author_id`` Integer Required ``messages_strategy`` String Required, values: keep, hide ======================= =============================== ===================== 200 OK ****** .. code:: json { "ban": { "author_id": 213124, "created_ts": 1278361287 } } Dashboard ######### Search Messages --------------- .. code:: GET /core/v1/talks/dashboard/messages?order=&limit=&offset=&status=&talk_id=&author_id= =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``order`` String Required, values: best, newest, oldest ``limit`` Integer Required ``offset`` Integer Required ``status`` String Optional, values: proposed, rejected, approved, featured ``talk_id`` String Optional ``author_id`` String Optional ``ids`` Comma-separated list of Strings Optional, values: message IDs =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "messages": [ { ... }, // See "Create Message" endpoint ... ], "authors": [ { ... }, // See "Create Message" endpoint ... ], "bans": [ {"author_id": 123, "created_ts": 1275628975}, ... ], "counts": { "messages": 26 }, } Update Messages --------------- .. code:: POST /core/v1/talks/dashboard/messages?order=&limit=&offset=&status=&talk_id=&author_id= { "changes": [ {"status": ""}, {"text": ""} ] } =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } ``order`` String Required, values: best, newest, oldest ``limit`` Integer Required ``offset`` Integer Required ``status`` String Optional, values: proposed, rejected, approved, featured ``talk_id`` String Optional ``author_id`` String Optional ``ids`` Comma-separated list of Strings Optional, values: message IDs ``text`` String Required for the change ``status`` String Required for the change, values: proposed, rejected, approved, featured =================== =============================== ===================== 200 OK ****** .. code:: json {} Settings ######## Get Global Settings ------------------- .. code:: GET /core/v1/talks/settings =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "settings": { "review": {"is_enabled": true}, "rating": {"formula": "message_likes * 10 + replies_likes"}, "words_per_message": {"min": 0, "max": null}, "allowed_html_tags": ["p", "b", "i", "strong", "em"] } } Set Global Settings ------------------- .. code:: POST /core/v1/talks/settings { "settings": { "review": {"is_enabled": false}, "rating": {"formula": "message_likes * 10 + replies_likes * 2"}, "words_per_message": {"min": 20, "max": 250}, "allowed_html_tags": ["p", "b", "i", "strong", "em", "a"] } } =================== =============================== ===================== Parameter Type Description =================== =============================== ===================== ``auth_token_type`` String Required, values: jwt ``auth_token`` String Required, values: {"user_id": } =================== =============================== ===================== 200 OK ****** .. code:: json :force: { "settings": { "review": {"is_enabled": false}, "rating": {"formula": "message_likes * 10 + replies_likes * 2"}, "words_per_message": {"min": 20, "max": 250}, "allowed_html_tags": ["p", "b", "i", "strong", "em", "a"] } }