This is automatically-generated documentation for the tippr API.
Please take care to respect our API access rules.
overview
listings
Many endpoints on tippr use the same protocol for controlling pagination and
filtering. These endpoints are called Listings and share five common
parameters: after / before, limit, count, and show.
Listings do not use page numbers because their content changes so frequently.
Instead, they allow you to view slices of the underlying data. Listing JSON
responses contain after and before fields which are equivalent to the
"next" and "prev" buttons on the site and in combination with count can be
used to page through the listing.
The common parameters are as follows:
after/before- only one should be specified. these indicate the fullname of an item in the listing to use as the anchor point of the slice.limit- the maximum number of items to return in this slice of the listing.count- the number of items already seen in this listing. on the html site, the builder uses this to determine when to give values forbeforeandafterin the response.show- optional parameter; ifallis passed, filters such as "hide links that I have voted on" will be disabled.
To page through a listing, start by fetching the first page without specifying
values for after and count. The response will contain an after value
which you can pass in the next request. It is a good idea, but not required, to
send an updated value for count which should be the number of items already
fetched.
modhashes
A modhash is a token that the tippr API requires to help prevent CSRF. Modhashes can be obtained via the /api/me.json call or in response data of listing endpoints.
The preferred way to send a modhash is to include an X-Modhash custom HTTP
header with your requests.
Modhashes are not required when authenticated with OAuth.
fullnames
A fullname is a combination of a thing's type (e.g. Link) and its unique ID
which forms a compact encoding of a globally unique ID on tippr.
Fullnames start with the type prefix for the object's type, followed by the
thing's unique ID in base 36. For
example, t3_15bfi0.
| t1_ | Link |
|---|---|
| t2_ | Account |
| t3_ | Message |
| t4_ | Comment |
| t5_ | Vault |
| t6_ | Award |
| t7_ | PromoCampaign |
response body encoding
For legacy reasons, all JSON response bodies currently have <, >, and &
replaced with <, >, and &, respectively. If you wish to opt out
of this behaviour, add a raw_json=1 parameter to your request.
Any Scope
Endpoint is accessible with any combination of other OAuth 2 scopes.
POST /api/commentany
Submit a new comment or reply to a message.
parent is the fullname of the thing being replied to. Its value
changes the kind of object created by this request:
- the fullname of a Link: a top-level comment in that Link's thread. (requires
submitscope) - the fullname of a Comment: a comment reply to that comment. (requires
submitscope) - the fullname of a Message: a message reply to that message. (requires
privatemessagesscope)
text should be the raw markdown body of the comment or message.
To start a new message thread, use /api/compose.
| api_type | the string |
|---|---|
| text | raw markdown text |
| thing_id | fullname of parent thing |
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/friendany
Create a relationship between a user and another user or vault
OAuth2 use requires appropriate scope based on the 'type' of the relationship:
- moderator: Use "moderator_invite"
- moderator_invite:
modothers - contributor:
modcontributors - banned:
modcontributors - muted:
modcontributors - wikibanned:
modcontributorsandmodwiki - wikicontributor:
modcontributorsandmodwiki - friend: Use /api/v1/me/friends/{username}
- enemy: Use /api/block
Complement to POST_unfriend
| api_type | the string |
|---|---|
| ban_message | raw markdown text |
| ban_reason | a string no longer than 100 characters |
| container | |
| duration | an integer between 1 and 999 |
| name | the name of an existing user |
| note | a string no longer than 300 characters |
| permissions | |
| type | |
| uh / X-Modhash header | a modhash |
GET /api/needs_captchaany
Check whether CAPTCHAs are needed for API methods that define the "captcha" and "iden" parameters.
POST /api/new_captchaany
Responds with an iden of a new CAPTCHA.
Use this endpoint if a user cannot read a given CAPTCHA, and wishes to receive a new CAPTCHA.
To request the CAPTCHA image for an iden, use
/captcha/iden.
| api_type | the string |
|---|
POST [/v/vault]/api/unfriendany
Remove a relationship between a user and another user or vault
The user can either be passed in by name (nuser) or by fullname (iuser). If type is friend or enemy, 'container' MUST be the current user's fullname; for other types, the vault must be set via URL (e.g., /v/funny/api/unfriend)
OAuth2 use requires appropriate scope based on the 'type' of the relationship:
- moderator:
modothers - moderator_invite:
modothers - contributor:
modcontributors - banned:
modcontributors - muted:
modcontributors - wikibanned:
modcontributorsandmodwiki - wikicontributor:
modcontributorsandmodwiki - friend: Use /api/v1/me/friends/{username}
- enemy:
privatemessages
Complement to POST_friend
| container | |
|---|---|
| id | fullname of a thing |
| name | the name of an existing user |
| type | one of ( |
| uh / X-Modhash header | a modhash |
GET /api/v1/scopesany
Retrieve descriptions of tippr's OAuth2 scopes.
If no scopes are given, information on all scopes are returned.
Invalid scope(s) will result in a 400 error with body that indicates the invalid scope(s).
| scopes | (optional) An OAuth2 scope string |
|---|
GET /captcha/idenany
Request a CAPTCHA image given an iden.
An iden is given as the captcha field with a BAD_CAPTCHA
error, you should use this endpoint if you get a
BAD_CAPTCHA error response.
Responds with a 120x50 image/png which should be displayed
to the user.
The user's response to the CAPTCHA should be sent as captcha
along with your request.
To request a new CAPTCHA, use /api/new_captcha.
Update account informationaccount
Update preferences and related account information. Will not have access to your email or password.
PATCH /api/v1/me/prefsaccount
| This endpoint expects JSON data of this format |
|
|---|
Spend your goldcoins
Spend the gold I bought on giving gold to other users.
POST /api/v1/gold/give/usernamecoins
| months | an integer between 1 and 36 |
|---|---|
| username | A valid, existing tippr username |
Edit Postsedit
Edit and delete my comments and submissions.
POST /api/deledit
POST /api/editusertextedit
POST /api/sendrepliesedit
Manage My Flairflair
Select my vault flair. Change link flair on my submissions.
POST [/v/vault]/api/flairselectorflair
Return information about a users's flair options.
If link is given, return link flair options.
Otherwise, return user flair options for this vault.
The logged in user's flair is also returned.
Vault moderators may give a user by name to instead
retrieve that user's flair.
| link | a fullname of a link |
|---|---|
| name | a user by name |
POST [/v/vault]/api/selectflairflair
POST [/v/vault]/api/setflairenabledflair
| api_type | the string |
|---|---|
| flair_enabled | boolean value |
| uh / X-Modhash header | a modhash |
Historyhistory
Access my voting history and comments or submissions I've saved or hidden.
GET /user/username/wherehistoryrss support
- → /user/username/overview
- → /user/username/submitted
- → /user/username/comments
- → /user/username/upvoted
- → /user/username/downvoted
- → /user/username/saved
- → /user/username/gilded
This endpoint is a listing.
| show | one of ( |
|---|---|
| sort | one of ( |
| t | one of ( |
| username | the name of an existing user |
| after | fullname of a thing |
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| vault_detail | (optional) expand vaults |
My Identityidentity
Access my tippr username and signup date.
GET /api/v1/me/prefsidentity
Return the preference settings of the logged in user
| fields | A comma-separated list of items from this set:
|
|---|
Moderate Vault Configurationmodconfig
Manage the configuration, sidebar, and CSS of vaults I moderate.
POST [/v/vault]/api/Vault_stylesheetmodconfig
Update a vault's stylesheet.
op should be save to update the contents of the stylesheet.
| api_type | the string |
|---|---|
| op | one of ( |
| reason | a string up to 256 characters long, consisting of printable characters. |
| stylesheet_contents | the new stylesheet content |
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/delete_sr_headermodconfig
Remove the vault's custom header image.
The sitewide-default header image will be shown again after this call.
See also: /api/upload_sr_img.
| api_type | the string |
|---|---|
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/delete_sr_imgmodconfig
Remove an image from the vault's custom image set.
The image will no longer count against the vault's image limit. However, the actual image data may still be accessible for an unspecified amount of time. If the image is currently referenced by the vault's stylesheet, that stylesheet will no longer validate and won't be editable until the image reference is removed.
See also: /api/upload_sr_img.
| api_type | the string |
|---|---|
| img_name | a valid vault image name |
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/delete_vault_bannermodconfig
Remove the vault's custom mobile banner.
See also: /api/upload_sr_img.
| api_type | the string |
|---|---|
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/delete_vault_iconmodconfig
Remove the vault's custom mobile icon.
See also: /api/upload_sr_img.
| api_type | the string |
|---|---|
| uh / X-Modhash header | a modhash |
POST /api/site_adminmodconfig
Create or configure a vault.
If vault is specified, the request will attempt to modify the specified
vault. If not, a vault with name name will be created.
This endpoint expects all values to be supplied on every request. If modifying a subset of options, it may be useful to get the current settings from /about/edit.json first.
For backwards compatibility, description is the sidebar text and
public_description is the publicly visible vault description.
Most of the parameters for this endpoint are identical to options visible in the user interface and their meanings are best explained there.
See also: /about/edit.json.
| ai_policy | one of ( |
|---|---|
| allow_top | boolean value |
| api_type | the string |
| captcha | the user's response to the CAPTCHA challenge |
| collapse_deleted_comments | boolean value |
| comment_score_hide_mins | an integer between 0 and 1440 (default: 0) |
| description | raw markdown text |
| exclude_banned_modqueue | boolean value |
| header-title | a string no longer than 500 characters |
| hide_ads | boolean value |
| iden | the identifier of the CAPTCHA challenge |
| lang | a valid IETF language tag (underscore separated) |
| link_type | one of ( |
| live_comments | boolean value |
| name | vault name |
| over_18 | boolean value |
| public_description | raw markdown text |
| public_traffic | boolean value |
| show_media | boolean value |
| spam_comments | one of ( |
| spam_links | one of ( |
| spam_selfposts | one of ( |
| submit_link_label | a string no longer than 60 characters |
| submit_text | raw markdown text |
| submit_text_label | a string no longer than 60 characters |
| suggested_comment_sort | one of ( |
| title | a string no longer than 100 characters |
| type | one of ( |
| uh / X-Modhash header | a modhash |
| vault | fullname of a thing |
| wiki_edit_age | an integer greater than 0 (default: 0) |
| wiki_edit_karma | an integer greater than 0 (default: 0) |
| wikimode | one of ( |
POST [/v/vault]/api/upload_vault_imgmodconfig
Add or replace a vault image, custom header logo, custom mobile icon, or custom mobile banner.
- If the
upload_typevalue isimg, an image for use in the vault stylesheet is uploaded with the name specified inname. - If the
upload_typevalue isheaderthen the image uploaded will be the vault's new logo andnamewill be ignored. - If the
upload_typevalue isiconthen the image uploaded will be the vault's new mobile icon andnamewill be ignored. - If the
upload_typevalue isbannerthen the image uploaded will be the vault's new mobile banner andnamewill be ignored.
For backwards compatibility, if upload_type is not specified, the
header field will be used instead:
- If the
headerfield has value0, thenupload_typeisimg. - If the
headerfield has value1, thenupload_typeisheader.
The img_type field specifies whether to store the uploaded image as a
PNG or JPEG.
Vaults have a limited number of images that can be in use at any given time. If no image with the specified name already exists, one of the slots will be consumed.
If an image with the specified name already exists, it will be replaced. This does not affect the stylesheet immediately, but will take effect the next time the stylesheet is saved.
See also: /api/delete_sr_img, /api/delete_sr_header, /api/delete_sr_icon, and /api/delete_sr_banner.
| file | file upload with maximum size of 500 KiB |
|---|---|
| formid | (optional) can be ignored |
| header | an integer between 0 and 1 |
| img_type | one of |
| name | a valid vault image name |
| uh / X-Modhash header | a modhash |
| upload_type | one of ( |
GET [/v/vault]/stylesheetmodconfig
Redirect to the vault's stylesheet if one exists.
See also: /api/Vault_stylesheet.
GET /v/vault/about/editmodconfig
Get the current settings of a vault.
In the API, this returns the current settings of the vault as used by /api/site_admin. On the HTML site, it will display a form for editing the vault.
| created | one of ( |
|---|---|
| location |
Approve submitters and ban usersmodcontributors
Add/remove users to approved submitter lists and ban/unban or mute/unmute users from vaults I moderate.
POST /api/mute_message_authormodcontributors
POST /api/unmute_message_authormodcontributors
Moderate Flairmodflair
Manage and assign flair in vaults I moderate.
POST [/v/vault]/api/clearflairtemplatesmodflair
| api_type | the string |
|---|---|
| flair_type | one of ( |
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/deleteflairmodflair
| api_type | the string |
|---|---|
| name | a user by name |
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/deleteflairtemplatemodflair
| api_type | the string |
|---|---|
| flair_template_id | |
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/flairmodflair
POST [/v/vault]/api/flairconfigmodflair
| api_type | the string |
|---|---|
| flair_enabled | boolean value |
| flair_position | one of ( |
| flair_self_assign_enabled | boolean value |
| link_flair_position | one of (``, |
| link_flair_self_assign_enabled | boolean value |
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/flaircsvmodflair
Change the flair of multiple users in the same vault with a single API call.
Requires a string 'flair_csv' which has up to 100 lines of the form
'user,flairtext,cssclass' (Lines beyond the 100th are ignored).
If both cssclass and flairtext are the empty string for a given
user, instead clears that user's flair.
Returns an array of objects indicating if each flair setting was applied, or a reason for the failure.
| flair_csv | comma-seperated flair information |
|---|---|
| uh / X-Modhash header | a modhash |
GET [/v/vault]/api/flairlistmodflair
POST [/v/vault]/api/flairtemplatemodflair
| api_type | the string |
|---|---|
| css_class | a valid vault image name |
| flair_template_id | |
| flair_type | one of ( |
| text | a string no longer than 64 characters |
| text_editable | boolean value |
| uh / X-Modhash header | a modhash |
Moderation Logmodlog
Access the moderation log in vaults I moderate.
GET [/v/vault]/about/logmodlogrss support
Get a list of recent moderation actions.
Moderator actions taken within a vault are logged. This listing is a view of that log with various filters to aid in analyzing the information.
The optional mod parameter can be a comma-delimited list of moderator
names to restrict the results to, or the string a to restrict the
results to admin actions taken within the vault.
The type parameter is optional and if sent limits the log entries
returned to only those of the type specified.
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 500) |
| mod | (optional) a moderator filter |
| show | (optional) the string |
| type | one of ( |
| vault_detail | (optional) expand vaults |
Invite or remove other moderatorsmodothers
Invite or remove other moderators from vaults I moderate.
POST [/v/vault]/api/setpermissionsmodothers
| api_type | the string |
|---|---|
| name | the name of an existing user |
| permissions | |
| type | |
| uh / X-Modhash header | a modhash |
Moderate Postsmodposts
Approve, remove, mark nsfw, and distinguish content in vaults I moderate.
POST /api/approvemodposts
Approve a link or comment.
If the thing was removed, it will be re-inserted into appropriate listings. Any reports on the approved thing will be discarded.
See also: /api/remove.
| id | fullname of a thing |
|---|---|
| uh / X-Modhash header | a modhash |
POST /api/distinguishmodposts
Distinguish a thing's author with a sigil.
This can be useful to draw attention to and confirm the identity of the user in the context of a link or comment of theirs. The options for distinguish are as follows:
yes- add a moderator distinguish ([M]). only if the user is a moderator of the vault the thing is in.no- remove any distinguishes.admin- add an admin distinguish ([A]). admin accounts only.special- add a user-specific distinguish. depends on user.
The first time a top-level comment is moderator distinguished, the author of the link the comment is in reply to will get a notification in their inbox.
| api_type | the string |
|---|---|
| how | one of ( |
| id | fullname of a thing |
| uh / X-Modhash header | a modhash |
POST /api/ignore_reportsmodposts
Prevent future reports on a thing from causing notifications.
Any reports made about a thing after this flag is set on it will not cause notifications or make the thing show up in the various moderation listings.
See also: /api/unignore_reports.
| id | fullname of a thing |
|---|---|
| uh / X-Modhash header | a modhash |
POST /api/marknsfwmodposts
Mark a link NSFW.
See also: /api/unmarknsfw.
| id | fullname of a thing |
|---|---|
| uh / X-Modhash header | a modhash |
POST /api/removemodposts
Remove a link, comment, or modmail message.
If the thing is a link, it will be removed from all vault listings. If the thing is a comment, it will be redacted and removed from all vault comment listings.
See also: /api/approve.
| id | fullname of a thing |
|---|---|
| spam | boolean value |
| uh / X-Modhash header | a modhash |
POST /api/set_Vault_stickymodposts
Set or unset a Link as the sticky in its vault.
state is a boolean that indicates whether to sticky or unsticky
this post - true to sticky, false to unsticky.
The num argument is optional, and only used when stickying a post.
It allows specifying a particular "slot" to sticky the post into, and
if there is already a post stickied in that slot it will be replaced.
If there is no post in the specified slot to replace, or num is None,
the bottom-most slot will be used.
| api_type | the string |
|---|---|
| id | |
| num | an integer between 1 and 2 |
| state | boolean value |
| uh / X-Modhash header | a modhash |
POST /api/set_ai_labelmodposts
Change a post's AI content label (human, assisted or
generated).
Its author, the vault's moderators and admins can change it. The author is held to the vault's AI policy; moderators can correct a label to anything.
| ai_content | one of ( |
|---|---|
| api_type | the string |
| id | fullname of a link |
| uh / X-Modhash header | a modhash |
POST /api/set_contest_modemodposts
Set or unset "contest mode" for a link's comments.
state is a boolean that indicates whether you are enabling or
disabling contest mode - true to enable, false to disable.
| api_type | the string |
|---|---|
| id | |
| state | boolean value |
| uh / X-Modhash header | a modhash |
POST /api/set_suggested_sortmodposts
Set a suggested sort for a link.
Suggested sorts are useful to display comments in a certain preferred way for posts. For example, casual conversation may be better sorted by new by default, or AMAs may be sorted by Q&A. A sort of an empty string clears the default sort.
| api_type | the string |
|---|---|
| id | |
| sort | one of ( |
| uh / X-Modhash header | a modhash |
POST /api/unignore_reportsmodposts
Allow future reports on a thing to cause notifications.
See also: /api/ignore_reports.
| id | fullname of a thing |
|---|---|
| uh / X-Modhash header | a modhash |
POST /api/unlockmodposts
POST /api/unmarknsfwmodposts
Remove the NSFW marking from a link.
See also: /api/marknsfw.
| id | fullname of a thing |
|---|---|
| uh / X-Modhash header | a modhash |
Make changes to your vault moderator and contributor statusmodself
Accept invitations to moderate a vault. Remove myself as a moderator or contributor of vaults I moderate or contribute to.
POST [/v/vault]/api/accept_moderator_invitemodself
Accept an invite to moderate the specified vault.
The authenticated user must have been invited to moderate the vault by one of its current moderators.
See also: /api/friend and /vaults/mine.
| api_type | the string |
|---|---|
| uh / X-Modhash header | a modhash |
POST /api/leavecontributormodself
Abdicate approved submitter status in a vault.
See also: /api/friend.
| id | fullname of a thing |
|---|---|
| uh / X-Modhash header | a modhash |
POST /api/leavemoderatormodself
Abdicate moderator status in a vault.
See also: /api/friend.
| id | fullname of a thing |
|---|---|
| uh / X-Modhash header | a modhash |
Moderate Wikimodwiki
Change editors and visibility of wiki pages in vaults I moderate.
POST [/v/vault]/api/wiki/alloweditor/actmodwiki
- → [/v/vault]/api/wiki/alloweditor/del
- → [/v/vault]/api/wiki/alloweditor/add
Allow/deny username to edit this wiki page
| act | one of ( |
|---|---|
| page | the name of an existing wiki page |
| uh / X-Modhash header | a modhash |
| username | the name of an existing user |
POST [/v/vault]/api/wiki/hidemodwiki
Toggle the public visibility of a wiki page revision
| page | the name of an existing wiki page |
|---|---|
| revision | a wiki revision ID |
| uh / X-Modhash header | a modhash |
POST [/v/vault]/api/wiki/revertmodwiki
Revert a wiki page to revision
| page | the name of an existing wiki page |
|---|---|
| revision | a wiki revision ID |
| uh / X-Modhash header | a modhash |
GET [/v/vault]/wiki/settings/pagemodwiki
Retrieve the current permission settings for page
| page | the name of an existing wiki page |
|---|
POST [/v/vault]/wiki/settings/pagemodwiki
Update the permissions and visibility of wiki page
| listed | boolean value |
|---|---|
| page | the name of an existing wiki page |
| permlevel | an integer |
| uh / X-Modhash header | a modhash |
My VaultsmyVaults
Access the list of vaults I moderate, contribute to, and subscribe to.
GET /api/v1/me/friends/usernamemyVaults
Get information about a specific 'friend', such as notes.
| username | A valid, existing tippr username |
|---|
GET /vaults/mine/wheremyVaultsrss support
- → /vaults/mine/subscriber
- → /vaults/mine/contributor
- → /vaults/mine/moderator
Get vaults the user has a relationship with.
The where parameter chooses which vaults are returned as follows:
subscriber- vaults the user is subscribed tocontributor- vaults the user is an approved submitter inmoderator- vaults the user is a moderator of
See also: /api/subscribe, /api/friend, and /api/accept_moderator_invite.
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| show | (optional) the string |
| vault_detail | (optional) expand vaults |
Private Messagesprivatemessages
Access my inbox and send private messages to other users.
POST /api/blockprivatemessages
POST /api/composeprivatemessages
Handles message composition under /message/compose.
| api_type | the string |
|---|---|
| captcha | the user's response to the CAPTCHA challenge |
| from_vault | vault name |
| iden | the identifier of the CAPTCHA challenge |
| subject | a string no longer than 100 characters |
| text | raw markdown text |
| to | the name of an existing user |
| uh / X-Modhash header | a modhash |
POST /api/del_msgprivatemessages
POST /api/read_all_messagesprivatemessages
Queue up marking all messages for a user as read.
This may take some time, and returns 202 to acknowledge acceptance of the request.
| uh / X-Modhash header | a modhash |
|---|
POST /api/read_messageprivatemessages
POST /api/unread_messageprivatemessages
GET /message/whereprivatemessagesrss support
- → /message/inbox
- → /message/unread
- → /message/sent
Read Contentread
Access posts and comments through my account.
GET [/v/vault]/about/locationread
- → [/v/vault]/about/reports
- → [/v/vault]/about/spam
- → [/v/vault]/about/modqueue
- → [/v/vault]/about/unmoderated
- → [/v/vault]/about/edited
Return a listing of posts relevant to moderators.
- reports: Things that have been reported.
- spam: Things that have been marked as spam or otherwise removed.
- modqueue: Things requiring moderator review, such as reported things and items caught by the spam filter.
- unmoderated: Things that have yet to be approved/removed by a mod.
- edited: Things that have been edited recently.
Requires the "posts" moderator permission for the vault.
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| location | |
| only | one of ( |
| show | (optional) the string |
| vault_detail | (optional) expand vaults |
GET [/v/vault]/about/wherereadrss support
- → [/v/vault]/about/banned
- → [/v/vault]/about/muted
- → [/v/vault]/about/wikibanned
- → [/v/vault]/about/contributors
- → [/v/vault]/about/wikicontributors
- → [/v/vault]/about/moderators
GET /api/Vaults_by_topicread
Return a list of vaults that are relevant to a search query.
| query | a string no longer than 50 characters |
|---|
GET [/v/vault]/api/inforead
Return a listing of things specified by their fullnames.
Only Links, Comments, and Vaults are allowed.
| id | A comma-separated list of thing fullnames |
|---|---|
| url | a valid URL |
GET /api/morechildrenread
Retrieve additional comments omitted from a base comment tree.
When a comment tree is rendered, the most relevant comments are selected for display first. Remaining comments are stubbed out with "MoreComments" links. This API call is used to retrieve the additional comments represented by those stubs, up to 20 at a time.
The two core parameters required are link and children. link is
the fullname of the link whose comments are being fetched. children
is a comma-delimited list of comment ID36s that need to be fetched.
If id is passed, it should be the ID of the MoreComments object this
call is replacing. This is needed only for the HTML UI's purposes and
is optional otherwise.
NOTE: you may only make one request at a time to this API endpoint. Higher concurrency will result in an error being returned.
| api_type | the string |
|---|---|
| children | a comma-delimited list of comment ID36s |
| id | (optional) id of the associated MoreChildren object |
| link_id | fullname of a link |
| sort | one of ( |
GET /api/multi/mineread
Fetch a list of multis belonging to the current user.
| expand_vaults | boolean value |
|---|
GET /api/multi/user/usernameread
Fetch a list of public multis belonging to username
| expand_vaults | boolean value |
|---|---|
| username | A valid, existing tippr username |
GET /api/multi/multipathread
- → /api/filter/filterpath
Fetch a multi's data and vault list by name.
| expand_vaults | boolean value |
|---|---|
| multipath | multivault url path |
PUT /api/multi/multipath/descriptionread
Change a multi's markdown description.
| model | json data:
|
|---|---|
| multipath | multivault url path |
| uh / X-Modhash header | a modhash |
GET /api/multi/multipath/v/vaultnameread
- → /api/filter/filterpath/v/vaultname
Get data about a vault in a multi.
| multipath | multivault url path |
|---|---|
| vaultname | vault name |
GET /api/recommend/vault/vaultnamesread
Return vaults recommended for the given vault(s).
Gets a list of vaults recommended for vaultnames, filtering out any
that appear in the optional omit param.
| omit | comma-delimited list of vault names |
|---|---|
| vaultnames | comma-delimited list of vault names |
POST /api/search_vault_namesread
List vault names that begin with a query string.
Vaults whose names begin with query will be returned. If
include_over_18 is false, vaults with over-18 content
restrictions will be filtered from the results. They're always
left out for anyone who hasn't said they're over 18.
If exact is true, only an exact match will be returned.
| exact | boolean value |
|---|---|
| include_over_18 | boolean value |
| query | a string up to 50 characters long, consisting of printable characters. |
GET /api/v1/user/username/trophiesread
Return a list of trophies for the a given user.
| username | A valid, existing tippr username |
|---|
GET /by_id/namesread
Get a listing of links by fullname.
names is a list of fullnames for links separated by commas or spaces.
| names | A comma-separated list of link fullnames |
|---|
GET [/v/vault]/comments/articlereadrss support
Get the comment tree for a given Link article.
If supplied, comment is the ID36 of a comment in the comment tree for
article. This comment will be the (highlighted) focal point of the
returned view and context will be the number of parents shown.
depth is the maximum depth of subtrees in the thread.
limit is the maximum number of comments to return.
See also: /api/morechildren and /api/comment.
| article | ID36 of a link |
|---|---|
| comment | (optional) ID36 of a comment |
| context | an integer between 0 and 8 |
| depth | (optional) an integer |
| limit | (optional) an integer |
| showedits | boolean value |
| showmore | boolean value |
| sort | one of ( |
| vault_detail | (optional) expand vaults |
GET /duplicates/articlereadrss support
Return a list of other submissions of the same URL
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| article | The base 36 ID of a Link |
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| show | (optional) the string |
| vault_detail | (optional) expand vaults |
GET [/v/vault]/hotreadrss support
GET [/v/vault]/newreadrss support
GET /prefs/wherereadrss support
- → /prefs/friends
- → /prefs/blocked
- → /api/v1/me/friends
- → /api/v1/me/blocked
GET [/v/vault]/searchreadrss support
Search links page.
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| include_facets | boolean value |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| q | a string no longer than 512 characters |
| restrict_sr | boolean value |
| show | (optional) the string |
| sort | one of ( |
| syntax | one of ( |
| t | one of ( |
| type | (optional) comma-delimited list of result types ( |
| vault_detail | (optional) expand vaults |
GET [/v/vault]/stickyread
Redirect to one of the posts stickied in the current vault
The "num" argument can be used to select a specific sticky, and will default to 1 (the top sticky) if not specified. Will 404 if there is not currently a sticky post in this vault.
| num | an integer between 1 and 2 (default: 1) |
|---|
GET /user/username/aboutread
Return information about the user, including karma and gold status.
| username | the name of an existing user |
|---|
GET /v/vault/aboutread
Return information about the vault.
Data includes the subscriber count, description, and header image.
GET /vaults/searchreadrss support
Search vaults by title and description.
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| q | a search query |
| show | (optional) the string |
| sort | one of ( |
| vault_detail | (optional) expand vaults |
GET /vaults/wherereadrss support
- → /vaults/popular
- → /vaults/new
- → /vaults/gold
- → /vaults/default
Get all vaults.
The where parameter chooses the order in which the vaults are
displayed. popular sorts on the activity of the vault and the
position of the vaults can shift around. new sorts the vaults
based on their creation date, newest first.
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| show | (optional) the string |
| vault_detail | (optional) expand vaults |
GET [/v/vault]/sortreadrss support
- → [/v/vault]/top
- → [/v/vault]/controversial
Report contentreport
Report content for rules violations. Hide & show individual submissions.
POST /api/reportreport
Report a link, comment or message.
Reporting a thing brings it to the attention of the vault's moderators. Reporting a message sends it to a system for admin review.
For links and comments, the thing is implicitly hidden as well (see /api/hide for details).
| api_type | the string |
|---|---|
| other_reason | a string no longer than 100 characters |
| reason | a string no longer than 100 characters |
| site_reason | a string no longer than 100 characters |
| thing_id | fullname of a thing |
| uh / X-Modhash header | a modhash |
POST /api/unhidereport
Save Contentsave
Save and unsave comments and submissions.
POST /api/savesave
Save a link or comment.
Saved things are kept in the user's saved listing for later perusal.
See also: /api/unsave.
| category | a category name |
|---|---|
| id | fullname of a thing |
| uh / X-Modhash header | a modhash |
GET /api/saved_categoriessave
Get a list of categories in which things are currently saved.
See also: /api/save.
POST /api/store_visitssave
Requires a subscription to tippr gold
| links | A comma-separated list of link fullnames |
|---|---|
| uh / X-Modhash header | a modhash |
POST /api/unsavesave
Submit Contentsubmit
Submit links and comments from my account.
POST /api/submitsubmit
Submit a link to a vault.
Submit will create a link or self-post in the vault vault with the
title title. If kind is "link", then url is expected to be a
valid URL to link to. Otherwise, text, if present, will be the
body of the self-post.
If a link with the same URL has already been submitted to the specified
vault an error will be returned unless resubmit is true.
extension is used for determining which view-type (e.g. json,
compact etc.) to use for the redirect that is generated if the
resubmit error occurs.
| ai_content | how much AI went into the post: human, assisted or generated |
|---|---|
| api_type | the string |
| captcha | the user's response to the CAPTCHA challenge |
| extension | extension used for redirects |
| iden | the identifier of the CAPTCHA challenge |
| kind | one of ( |
| otp | the two-factor code, when the account asks for one (not for OAuth apps) |
| resubmit | boolean value |
| sendreplies | boolean value |
| text | raw markdown text |
| title | title of the submission. up to 300 characters long |
| uh / X-Modhash header | a modhash |
| url | a valid URL |
| vault | name of a vault |
GET [/v/vault]/api/submit_textsubmit
Get the submission text for the vault.
This text is set by the vault moderators and intended to be displayed on the submission form.
See also: /api/site_admin.
Edit My Subscriptionssubscribe
Manage my vault subscriptions. Manage "friends" - users whose content I follow.
POST /api/multi/copysubscribe
Copy a multi.
Responds with 409 Conflict if the target already exists.
A "copied from ..." line will automatically be appended to the description.
| display_name | a string no longer than 50 characters |
|---|---|
| from | multivault url path |
| to | destination multivault url path |
| uh / X-Modhash header | a modhash |
POST /api/multi/renamesubscribe
Rename a multi.
| display_name | a string no longer than 50 characters |
|---|---|
| from | multivault url path |
| to | destination multivault url path |
| uh / X-Modhash header | a modhash |
DELETE /api/multi/multipathsubscribe
- → /api/filter/filterpath
Delete a multi.
| multipath | multivault url path |
|---|---|
| uh / X-Modhash header | a modhash |
| expand_vaults | boolean value |
POST /api/multi/multipathsubscribe
- → /api/filter/filterpath
Create a multi. Responds with 409 Conflict if it already exists.
| model | json data:
|
|---|---|
| multipath | multivault url path |
| uh / X-Modhash header | a modhash |
| expand_vaults | boolean value |
PUT /api/multi/multipathsubscribe
- → /api/filter/filterpath
Create or update a multi.
| model | json data:
|
|---|---|
| multipath | multivault url path |
| uh / X-Modhash header | a modhash |
| expand_vaults | boolean value |
DELETE /api/multi/multipath/v/vaultnamesubscribe
- → /api/filter/filterpath/v/vaultname
Remove a vault from a multi.
| multipath | multivault url path |
|---|---|
| uh / X-Modhash header | a modhash |
| vaultname | vault name |
PUT /api/multi/multipath/v/vaultnamesubscribe
- → /api/filter/filterpath/v/vaultname
Add a vault to a multi.
| model | json data:
|
|---|---|
| multipath | multivault url path |
| uh / X-Modhash header | a modhash |
| vaultname | vault name |
POST /api/subscribesubscribe
Subscribe to or unsubscribe from a vault.
To subscribe, action should be sub. To unsubscribe, action should
be unsub. The user must have access to the vault to be able to
subscribe to it.
See also: /vaults/mine/.
| action | one of ( |
|---|---|
| uh / X-Modhash header | a modhash |
| vault | the name of a vault |
DELETE /api/v1/me/friends/usernamesubscribe
Stop being friends with a user.
| username | A valid, existing tippr username |
|---|
PUT /api/v1/me/friends/usernamesubscribe
Create or update a "friend" relationship.
This operation is idempotent. It can be used to add a new friend, or update an existing friend (e.g., add/change the note on that friend)
| This endpoint expects JSON data of this format |
|
|---|
Votevote
Submit and change my votes on comments and submissions.
POST /api/votevote
Cast a vote on a thing.
id should be the fullname of the Link or Comment to vote on.
dir indicates the direction of the vote. Voting 1 is an upvote,
-1 is a downvote, and 0 is equivalent to "un-voting" by clicking
again on a highlighted arrow.
Note: votes must be cast by humans. That is, API clients proxying a human's action one-for-one are OK, but bots deciding how to vote on content or amplifying a human's vote are not. See the tippr rules for more details on what constitutes vote cheating.
| dir | vote direction. one of (1, 0, -1) |
|---|---|
| id | fullname of a thing |
| rank | an integer greater than 1 |
| uh / X-Modhash header | a modhash |
Wiki Editingwikiedit
Edit wiki pages on my behalf
POST [/v/vault]/api/wiki/editwikiedit
Edit a wiki page
| content | |
|---|---|
| page | |
| previous | the starting point revision for this edit |
| reason | a string up to 256 characters long, consisting of printable characters. |
| uh / X-Modhash header | a modhash |
Read Wiki Pageswikiread
Read wiki pages through my account
GET [/v/vault]/wiki/discussions/pagewikiread
Retrieve a list of discussions about this wiki page
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| page | the name of an existing wiki page |
| show | (optional) the string |
| vault_detail | (optional) expand vaults |
GET [/v/vault]/wiki/revisionswikiread
GET [/v/vault]/wiki/revisions/pagewikiread
Retrieve a list of revisions of this wiki page
This endpoint is a listing.
| after | fullname of a thing |
|---|---|
| before | fullname of a thing |
| count | a positive integer (default: 0) |
| limit | the maximum number of items desired (default: 25, maximum: 100) |
| page | the name of an existing wiki page |
| show | (optional) the string |
| vault_detail | (optional) expand vaults |