The current version of Weasyl, in some specified format. The format can be one of .json or .txt, or omitted for JSON by default. For example:
{"short_sha": "deadbeef"}
The currently logged-in user, as JSON. For example:
{"login": "weykent", "userid": 5756}
If there is no current user, the response will be a 401 Unauthorized.
A user’s avatar.
| Query Parameters: | |
|---|---|
|
|
The result will resemble:
{"avatar": "https://www.weasyl.com/static/user/66/42/8d/0a/3f/8c/5756/avatar.png"}
Users without an avatar will get the default avatar icon back.
A list of submissions from the front page, respecting the current user’s browsing settings.
| Query Parameters: | |
|---|---|
|
|
This will return at most 100 submissions. If count is more than 100, at most 100 submissions will be returned. It is possible to receive less than count submissions back if too many submissions are filtered by the user’s e.g. tag filters.
The result will be a JSON array of submission objects.
View a particular submission by its submitid.
| Query Parameters: | |
|---|---|
|
|
The result will be a JSON submission object.
Retrieve information about a user by login name.
The result will be a JSON user object.
List a user’s gallery by login name.
| Query Parameters: | |
|---|---|
|
|
This will return at most 100 submissions. If count is more than 100, at most 100 submissions will be returned.
The result will be a JSON object with three keys: submissions, backid, and nextid. submissions will be a JSON array of submission objects. backid and nexid are used in pagination.
List submissions in an authenticated user’s inbox.
| Query Parameters: | |
|---|---|
|
|
This will return at most 100 submissions. If count is more than 100, at most 100 submissions will be returned.
The result will be a JSON object with three keys: submissions, backtime, and nexttime. submissions will be a JSON array of submission objects. backtime and nextime are used in pagination.
List a summary of notifications for an authenticated user. The result will be a JSON object resembling:
{
"comments": 0,
"journals": 3,
"notifications": 1,
"submissions": 14,
"unread_notes": 0
}
Note
The result of this API endpoint is cached. New information is available only every three minutes or when a note arrives.
The standard OAuth2 authorization endpoint. Currently only authorization code grants with callback URIs are supported.
| Query Parameters: | |
|---|---|
|
|
On a successful authorization, the user agent will be redirected to the redirect_uri with query parameters of code and state. code will be a random string used to retrieve the authorization code grant, and state will be the same state as was passed originally.
The endpoint for fetching and refreshing OAuth2 tokens.
| Form Parameters: | |
|---|---|
|
|
Other form parameters are described for authorization code grants at <http://tools.ietf.org/html/rfc6749#section-4.1> and for refreshing tokens at <http://tools.ietf.org/html/rfc6749#section-6>.
Note
Access tokens currently expire after an hour, to be sure to use the provided refresh token before then.
A basic submission object resembles:
{ "media": {}, "owner": "Caffeinated-Owl", "owner_login": "caffeinatedowl", "posted_at": "2014-02-12T07:33:17Z" "rating": "general", "submitid": 466821, "subtype": "visual", "tags": [ "hunter", "snake", "pi" ], "title": "Tiny Little Pi", "type": "submission", }The type key will be one of "submission" or "character".
The subtype key for "submission" types will be one of "visual", "literary", or "multimedia".
The rating key will be one of "general", "moderate", "mature", or "explicit".
The media key is the submission’s media.
Slightly different keys are returned for the GET /api/submissions/(submitid)/view endpoint:
{ "comments": 0, "description": "Itty bitty little snake hunter", "embedlink": null, "favorited": false, "favorites": 3, "folder_name": null, "folderid": null, "friends_only": false, "owner": "Caffeinated-Owl", "owner_login": "caffeinatedowl", "owner_media": {}, "posted_at": "2014-02-12T07:33:17Z", "rating": "general", "media": {}, "submitid": 466821, "subtype": "visual", "tags": [ "hunter", "pi", "snake" ], "title": "Tiny Little Pi", "type": "submission", "views": 6 }The media key is the media for the submission itself, while the owner_media key is the media for the owner of the submission.
The embedlink key will be null for "visual" type submissions and potentially a URL for other submission types.
The description key is the HTML-rendered description of the submission.
The favorited key indicates whether or not the current user has favorited the submission.
A user object contains many keys. Some of these keys include:
- media
- The media of the specified user’s avatar and banner.
- profile_text
- The rendered HTML of the specified user’s description.
- recent_submissions
- An array of submission objects.
- recent_type
- What kind of submissions are in the recent_submissions array. Can be one of submissions, characters, or collections.
- relationship
- null if this is an unauthenticated request or an object representing aspects of the relationship between the current user and the specified user.
- show_favorites_bar
- Whether the specified user’s favorites are shown as icons at the top of the profile page.
- show_favorites_tab
- Whether the specified user’s favorites should be shown at all.
- statistics
- null if the specified user doesn’t allow statistics to be shown or an object of statistics about the specified user.
A user object resembles:
{
"banned": false,
"catchphrase": "",
"commission_info": {
"commissions": null,
"details": "<",
"price_classes": null,
"requests": null,
"trades": null
},
"created_at": "2012-11-03T17:01:37Z",
"featured_submission": null,
"folders": [],
"full_name": "weyk\u00ebnt",
"login_name": "weykent",
"media": {
"avatar": [
{
"mediaid": 937444,
"url": "https://www.weasyl.com/static/user/66/42/8d/0a/3f/8c//5756/avatar.png"
}
],
"banner": [
{
"mediaid": 937443,
"url": "https://www.weasyl.com/static/user/66/42/8d/0a/3f/8c//5756/banner.gif"
}
]
},
"profile_text": "<p>yo. I do weasyl coding and shit.</p><p>😼</p>",
"recent_submissions": [],
"recent_type": "collections",
"relationship": null,
"show_favorites_bar": false,
"show_favorites_tab": false,
"statistics": {
"faves_received": 0,
"faves_sent": 2,
"followed": 23,
"following": 56,
"journals": 0,
"page_views": 16354,
"submissions": 0,
"submit_views": 0
},
"stream_text": "",
"stream_url": "",
"streaming_status": "stopped",
"suspended": false,
"user_info": {
"age": null,
"aim": "",
"facebook": "",
"foursquare": "",
"gender": "h4x0r",
"googleplus": "",
"icq": "",
"location": "seattle, wa",
"msn": "",
"myspace": "",
"psn": "",
"reddit": "",
"skype": "",
"steam": "",
"tumblr": "",
"twitter": "",
"xboxlive": "",
"yahoo": "",
"youtube": ""
},
"username": "weykent"
}
media keys in Weasyl API responses take the form of a JSON object mapping descriptive names to media file objects.
The media file objects will have at least two keys: url, and mediaid. The mediaid is a unique identifier which unambiguously refers to a particular file stored by Weasyl. The url is one possible URL where the file can be downloaded. There can be multiple possible urls for a given mediaid. A mediaid can also be null to indicate the url is already unambiguous.
A media file object may also have another key: links. The links key is itself a media key, and allows media files to be linked to other media files. Currently, the only kind of link is "cover", which links a media file to its cover image.
For submissions, the possible descriptive names are "submission" for the original file uploaded by the user, "cover" for the submission’s cover image, and "thumbnail" for the submission’s thumbnail. The "submission" and "cover" names are optional for a submission, while the "thumbnail" name will always exist.
For users, the possible descriptive names are "avatar" for the user’s avatar and "banner" for the user’s banner. "banner" is optional while "avatar" will always exist.
Here is an example of the media for a visual submission:
{
"submission": [
{
"links": {
"cover": [
{
"mediaid": 1651999,
"url": "https://www.weasyl.com/static/media/..."
}
]
},
"mediaid": 1651999,
"url": "https://www.weasyl.com/static/media/..."
}
],
"thumbnail": [
{
"mediaid": 1652001,
"url": "https://www.weasyl.com/static/media/..."
}
],
"cover": [
{
"links": {
"cover": [
{
"mediaid": 1651999,
"url": "https://www.weasyl.com/static/media/..."
}
]
},
"mediaid": 1651999,
"url": "https://www.weasyl.com/static/media/..."
}
]
}
Pagination is done through backid and nextid (or, in some cases, backtime and nexttime) response keys and request query parameters. Paginated API endpoints will return JSON objects with backid and nextid keys to indicate how to find the previous and next pages of results.
If nextid is not null, there is a next page accessible by specifying that nextid as a query parameter, keeping all other query parameters the same. Similarly, if backid is not null, there is a previous page accessible by specifying that backid as a query parameter.
Authentication can be done in one of two ways: a Weasyl API key, or an OAuth2 bearer token.
Weasyl API keys are managed at <https://www.weasyl.com/control/apikeys>, and are extremely simple to use. To authenticate a request, set the X-Weasyl-API-Key header to the value of an API key, and the user agent will be authenticated as the user who created the key.
To authenticate a request with an OAuth2 bearer token, pass an Authorization: Bearer header along with the token, as described in <http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-20#section-2.1>.
At the moment, these are the non-200 OK statuses potentially emitted by the Weasyl API:
In addition to sending a non-200 OK response, errors are signaled by returning a JSON object with an error key. The value of this key will be an object containing either a code key, a name key, or neither. An object with a code or name key will unambiguously specify the problem encountered. An object with neither key indicates that an unexpected error was encountered.
An error response resembles the following:
{
"error": {
"name": "RatingExceeded"
}
}
If a bearer token has expired, the WWW-Authenticate header in the response will include error="invalid_token".