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

{}