Talks API

Runtime

Get Talk

GET /core/v1/talks/<talk_id>?include=<inclusions>&mode=<mode>&forced_ids=<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

 {
   "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

GET /core/v1/talks/<talk_id>/messages?order=<order>&limit=<limit>&offset=<offset>&excluded_ids=<excluded_ids>&mode=<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

 {
   "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

POST /core/v1/talks/<talk_id>/messages
{
  "text": "<text>"
}

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <author_id>}
talk_id	String	Required
text	String	Required

200 OK

 {
   "message": {
     "id": "5b27aa52bd96bc0e3ec0eaf9",
     "html": "<p>Hey hey!</p>",
     "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

GET /core/v1/talks/<talk_id>/messages/<message_id>

Parameter	Type	Description
talk_id	String	Required
message_id	String	Required

200 OK

 {
   "message": {
     "id": "5b27aa52bd96bc0e3ec0eaf9",
     "html": "<p>Hey hey!</p>",
     "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

POST /core/v1/talks/<talk_id>/messages/<message_id>
{
  "changes": [
    {"status": "<status>"},
    {"text": "<text>"}
  ]
}

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <author_id or admin_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

 {
   "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

GET /core/v1/talks/<talk_id>/messages/<message_id>/replies?order=<order>&limit=<limit>&offset=<offset>&excluded_ids=<excluded_ids>&mode=<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

 {
   "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

POST /core/v1/talks/<talk_id>/messages/<message_id>/replies
{
  "text": "<text>"
}

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <author_id>}
talk_id	String	Required
message_id	String	Required
text	String	Required

200 OK

 {
   "message": {
     "id": "5b27aa52bd96bc0e3ec0eaf9",
     "html": "<p>Hey hey!</p>",
     "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

POST /core/v1/talks/<talk_id>/messages/<message_id>/reactions
{
  "reaction": "<reaction>"
}

DELETE /core/v1/talks/<talk_id>/messages/<message_id>/reactions

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <author_id>}
talk_id	String	Required
message_id	String	Required
reaction	String	Required, values: like, dislike

200 OK

 {
   "message": {
     "id": "5b27aa52bd96bc0e3ec0eaf9",
     "html": "<p>Hey hey!</p>",
     "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

POST /core/v1/talks/<talk_id>/messages/<message_id>/reports
{
  "reason": "<reason>",
  "description": "<description>"
}

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <author_id>}
talk_id	String	Required
message_id	String	Required
reason	String	Required, values: spam, abuse, porno, violence, other
description	String	Optional

200 OK

 {
   "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

GET /core/v1/talks/<talk_id>/messages/<message_id>/reports

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <admin_id>}
talk_id	String	Required
message_id	String	Required

200 OK

 {
   "report": {
     { ... },  // See "Report Message" endpoint
     ...
   }
 }

Ban/Unban Author

POST /core/v1/talks/bans
{
  "author_id": "<author_id>",
  "messages": "<messages_strategy>"
}

DELETE /core/v1/talks/bans

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <admin_id>}
author_id	Integer	Required
messages_strategy	String	Required, values: keep, hide

200 OK

{
  "ban": {
    "author_id": 213124,
    "created_ts": 1278361287
  }
}

Dashboard

Search Messages

GET /core/v1/talks/dashboard/messages?order=<order>&limit=<limit>&offset=<offset>&status=<status>&talk_id=<talk_id>&author_id=<author_id>

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <admin_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

 {
   "messages": [
     { ... }, // See "Create Message" endpoint
     ...
   ],
   "authors": [
     { ... }, // See "Create Message" endpoint
     ...
   ],
   "bans": [
     {"author_id": 123, "created_ts": 1275628975},
     ...
   ],
   "counts": {
     "messages": 26
   },
 }

Update Messages

POST /core/v1/talks/dashboard/messages?order=<order>&limit=<limit>&offset=<offset>&status=<status>&talk_id=<talk_id>&author_id=<author_id>
{
  "changes": [
    {"status": "<status>"},
    {"text": "<text>"}
  ]
}

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <admin_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

{}

Settings

Get Global Settings

GET /core/v1/talks/settings

Parameter	Type	Description
auth_token_type	String	Required, values: jwt
auth_token	String	Required, values: {“user_id”: <admin_id>}

200 OK

 {
   "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

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”: <admin_id>}

200 OK

 {
   "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"]
   }
 }