API Documentation

This page is generated by the TalkSpar application introspecting its own routing functions. Nifty.

The base URL is https://talkspar.com/api/v2

API requests must be authenticated with an access token. To obtain an access token, follow these instructions.

auth

`PATCH /auth`

Revoke the current Access Token. A new Access Token may be obtained using the Refresh Token. Permanent authorizations only.

`DELETE /auth`

Revoke the current authorization. A new Access Token may not be obtained without the user going through the OAuth process again.

comments

`POST /comments`

oauth scopes: create
Create a comment

Required form data:

parent_fullname - The fullname of the post or comment that is being replied to
body - Raw comment text

Optional file data:

file - An image to upload and append to the comment body. Requires premium.

`GET /comments`

oauth scopes: read
Get all comments

Optional query parameters:
* `page` - Page of results to return. Default `1`

`GET /comments/<cid>`

oauth scopes: read
Fetch a single comment and up to 5 total layers above and below.

URL path parameters:

cid - The base 36 comment id

Optional query parameters:

context - Integer between 0 and 4 inclusive. Number of generations of parent comments to fetch. Default 0

`PATCH /comments/<cid>`

oauth scopes: update
Edit a comment.

URL path parameters:

cid - The base 36 id of the comment to edit

Required form data:

body - The new raw comment text

`DELETE /comments/<cid>`

oauth scopes: delete
Delete your comment.

URL path parameters:

cid - The base 36 id of the comment to delete

`GET /comments/<cid>/votes`

oauth scopes: read
Get public vote information about a comment.

URL path parameters:
* `cid` - The base 36 comment ID

`POST /comments/<cid>/votes/<x>`

oauth scopes: vote
Cast a vote on a comment.

URL path parameters:
* `cid` - The base 36 comment ID
* `x` - One of `1`, `0`, or `-1`, indicating upvote, novote, or downvote respectively

guilds

`POST /guilds`

oauth scopes: create
Create a Guild

Required form data:
* `name` - Name of Guild to create
* `category` - The ID of the subcategory with which to associate the new Guild (obtained from `GET /categories`)

Optional form data:
* `description` - Guild description

`GET /guilds`

oauth scopes: read
Get a listing of guilds

Optional query parameters:
* `sort` - One of `trending`, `new`, or `subs`. Default `trending`.
* `page` - Page of results to return. Defualt `1`.

`GET /guilds/<guildname>/comments`

oauth scopes: read
Get comments in a guild

URL parameters:
* `guildname` - The name of a guild

Optional query parameters:
* `page` - Page of comments to get. Default `1`.

`PATCH /guilds/<guildname>/comments/<cid>/herald`

guildmaster permissions: content
oauth scopes: guildmaster
Toggle Herald status on your comment.

URL path parameters:
* `guildname` - The guild in which you are a guildmaster
* `cid` - The base 36 comment ID

`PATCH /guilds/<guildname>/comments/<cid>/pin`

guildmaster permissions: content
oauth scopes: guildmaster
Toggle pin status on a top-level comment.

URL path parameters:

guildname - The guild in which you are a guildmaster
cid - The base 36 comment id

`POST /guilds/<guildname>/contributors`

guildmaster permissions: access
oauth scopes: guildmaster
Approve a user as a Contributor in a Guild

URL path parameters:
* `guildname` - The guild in which you are a guildmaster

Required form data:
* `username` - The username of the user to approve.

`GET /guilds/<guildname>/contributors`

guildmaster permissions: access
oauth scopes: read, guildmaster
View guild contributor list.

URL path parameters:
* `guildname` - The guild in which you are a guildmaster

Optional query parameters
* `page` - The page of items to view. Default `1`.

`DELETE /guilds/<guildname>/contributors`

guildmaster permissions: access
oauth scopes: guildmaster
Un-approve a user as a Contributor in a Guild

URL path parameters:
* `guildname` - The guild in which you are a guildmaster

Required form data:
* `username` - The username of the user to remove contributor status from.

`POST /guilds/<guildname>/exiles`

guildmaster permissions: access
oauth scopes: guildmaster
Exile a user from a Guild

URL path parameters:
* `guildname` - The guild in which you are a guildmaster

Required form data:
* `username` - The username of the user to exile.

Optional form data:
* `thing` - The fullname of the post or comment to associate with the exile

`GET /guilds/<guildname>/exiles`

guildmaster permissions: access
oauth scopes: read, guildmaster
View guild exile entries.

URL path parameters:
* `guildname` - The guild in which you are a guildmaster

Optional query parameters
* `page` - The page of items to view. Default `1`.

`DELETE /guilds/<guildname>/exiles/<username>`

guildmaster permissions: access
oauth scopes: guildmaster
Un-exile a user from a Guild

URL path parameters:
* `guildname` - The guild in which you are a guildmaster
* `username` - The username of the user to exile.

`GET /guilds/<guildname>/modlogs`

oauth scopes: read
View guild mod log data.

URL path parameters:
* `guildname` - The guild in which you are a guildmaster

Optional query parameters
* `page` - The page of items to view. Default `1`.

`GET /guilds/<guildname>/modlogs/<id>`

oauth scopes: read
View a guild mod log entry.

URL path parameters:
* `guildname` - The guild in which you are a guildmaster
* `id` - The base 36 id of the mod log entry

`GET /guilds/<guildname>/modqueue`

oauth scopes: read, guildmaster
guildmaster permissions: content
Get reported posts in a guild.

URL path parameters:
* `guildname` - The name of a guild

`GET /guilds/<guildname>/mods`

oauth scopes: read
Get a list of users who are guildmasters of a guild.

URL path parameters:
* `guildname` - The name of a guild

`GET /guilds/<guildname>/submissions`

oauth scopes: read
Get a guild's submissions

URL path parameter:
* `guildname` - The name of the guild

Optional query parameters:
* `page` - Page number. Contents are returned in pages of 25 entries. Default `1`.
* `sort` - Sort order. One of `hot`, `top`, `new`, `old`, `disputed`, and `activity`. Default `hot`.
* `t` - Time filter. One of `day`, `week`, `month`, `year`, and `all`. Default `all`.

`PATCH /guilds/<guildname>/submissions/<pid>/approve`

guildmaster permissions: content
oauth scopes: guildmaster
Dismiss reports on submission and keep it in your guild.

URL path parameters:
* `guildname` - The guild in which you are a guildmaster
* `pid` - The base 36 id of the post

`PATCH /guilds/<guildname>/submissions/<pid>/herald`

guildmaster permissions: content
oauth scopes: guildmaster
Toggle Herald status on your post.

URL path parameters:
* `guildname` - The guild in which you are a guildmaster
* `pid` - The base 36 post ID

`PATCH /guilds/<guildname>/submissions/<pid>/kick`

guildmaster permissions: content
oauth scopes: guildmaster
Kick a post from your guild.

URL path parameters:
* `guildname` - The guild in which you are a guildmaster
* `pid` - The base 36 post ID

`PATCH /guilds/<guildname>/submissions/<pid>/pin/<x>`

guildmaster permissions: content
oauth scopes: guildmaster
Set pin status on a post

URL path parameters:
* `guildname` - The guild to pin the post in
* `pid` - The base 36 id of the post to pin
* `x` - One of `0` or `1`, corresponding to unpinned and pinned statuses respectively

`PATCH /guilds/<guildname>/toggle_bell`

oauth scopes: update
Toggle notifications for new posts in a guild. You must be a member of the guild.

URL path parameters:
* `guildname` - The name of a guild.

Optional query parameters:
`page` - Page of results to return. Default `1`

Optional query parameters:
* `page` - Page of results to return. Default `1`.

`GET /me/submissions`

oauth scopes: read
Get personalized home page based on subscriptions and personal settings.

Optional query parameters:
* `sort` - One of `hot`, `new`, `top`, `disputed`, `activity`. Default `hot`.
* `t` - One of `day`, `week`, `month`, `year`, `all`. Default `all`.
* `page` - Page of results to return. Default `1`.

`PATCH /me/submissions/<pid>/unyank`

oauth scopes: update
Un-yank your post back to +general

URL path parameters:
* `pid` - The base 36 id of the post to un-yank

`POST /me/subscriptions/<guildname>`

Subscribe to a Guild.

URL path parameters:
* `guildname` - The name of a guild

`DELETE /me/subscriptions/<guildname>`

Unsubscribe from a Guild.

URL path parameters:
* `guildname` - The name of a guild

`GET /me/users`

oauth scopes: read
Get users that the authenticated user is following

Optional query parameters:
`page` - Page of results to return. Default `1`

submissions

`POST /submissions`

oauth scopes: create
Create a post

Required form data:
* `title` - The post title
* `guild` - The name of the guild to submit to

At least one of the following form items is required:
* `url` - The link being submitted. Uploading an image file counts as a url.
* `body` - The text body of the post

Optional file data:
* `file` - An image to upload as the post target. Requires premium or a minimum Rep threshold.

`GET /submissions`

oauth scopes: read
Get all posts, minus filtered content based on personal settings.

Optional query parameters:
* `sort` - One of `hot`, `new`, `top`, `disputed`, `activity`. Default `hot`.
* `t` - One of `day`, `week`, `month`, `year`, `all`. Default `all`.
* `page` - Page of results to return. Default `1`.

`GET /submissions/<pid>`

oauth scopes: read
Get a single submission (without comments).

URL path parameters:
* `pid` - The base 36 post id

`PATCH /submissions/<pid>`

oauth scopes: update
Edit your post text.

URL path parameters:
* `pid` - The base 36 id of the post to edit

Required form data:
* `body` - The new raw post text

`DELETE /submissions/<pid>`

oauth scopes: delete
Delete your post.

URL path parameters:
* `pid` - The base 36 id of the post being deleted

`GET /submissions/<pid>/comments`

oauth scopes: read
Get the comment tree for a submission.

URL path parameters:
* `pid` - The base 36 post id

Optional query parameters:
* `sort` - Comment sort order. One of `hot`, `new`, `top`, `disputed`, `old`. Default `hot`.

`PUT /submissions/<pid>/thumb`

oauth scopes: identity
Retry thumbnail scraping on your post.

URL path parameters:
* `pid` - The base 36 post id.

`PATCH /submissions/<pid>/toggle_nsfl`

oauth scopes: update
Toggle "NSFL" status on a post.

URL path parameters:
* `pid` - The base 36 post id.

`PATCH /submissions/<pid>/toggle_nsfw`

oauth scopes: update
Toggle "NSFW" status on a post.

URL path parameters:
* `pid` - The base 36 post id.

`GET /submissions/<pid>/votes`

oauth scopes: read
Get public vote information about a post.

URL path parameters:
* `pid` - The base 36 post ID

`POST /submissions/<pid>/votes/<x>`

oauth scopes: vote
Cast a vote on a post.

URL path parameters:
* `pid` - The base 36 post ID
* `x` - One of `1`, `0`, or `-1`, indicating upvote, novote, or downvote respectively

users

`GET /users/<username>`

oauth scopes: read
Get information about another user.

URL path parameters:

username - A user's name.

`GET /users/<username>/comments`

oauth scopes: read
Get comments created by another user.

URL path parameters:

username - The user whose comments are being fetched.

Optional query parameters:

sort - One of hot, new, old, top, or disputed. Default new.
t - One of day, week, month, year, all. Default all.
page - Page of results to return. Default 1.

`POST /users/<username>/follow`

Follow another user.

URL path parameters:

username - A user's name.

`DELETE /users/<username>/follow`

Unfollow another user.

URL path parameters:

username - A user's name.

`GET /users/<username>/submissions`

oauth scopes: read
Get posts created by another user.

URL path parameters:

username - The user whose posts are being fetched.

Optional query parameters:

sort - One of hot, new, old, top, activity, or disputed. Default new.
t - One of day, week, month, year, all. Default all.
page - Page of results to return. Default 1.

`POST /users/<username>/toggle_bell`

oauth scopes: update
Toggle notifications for new posts by a user. You must be following the user.

URL path parameters:

username - Another user's name