deviant art





Login
Join deviantART for FREE Take the Tour Lost Password?
Deviant Login
Buy Art Buy deviantWEAR Buy adCast Buy Premium Upgrade
Shop
 Join deviantART for FREE Take the Tour

Developers

Submit creative media to deviantART with the Sta.sh API

The goal of the Sta.sh API is to enable your application or website to very simply upload creative content to deviantART.

The API can receive any file format. Some like JPG, PNG, GIF, HTML and plain text will be displayed directly. Other file types that we don't currently display natively on deviantART will be made available for download - they can have a preview image.

The Sta.sh API always acts on behalf of a deviantART user, who has been authenticated with OAuth 2.0. By the time your application or website calls the Sta.sh API, it needs to provide an OAuth 2.0 token associated with the user.

The URL of a request differs depending on which version of OAuth 2.0 you've authenticated the user with. The drafts are not interchangeable, a user authenticated through draft 10 can only call the draft 10 Sta.sh endpoint.

We advise you to first do a placebo call before you do a Sta.sh API call that includes a file. This is is because whenever OAuth 2.0 needs the user to reauthenticate, the API call fails with an appropriate error status. If you are uploading a big file, you will only get the OAuth 2.0 error at the very end of the upload.

Sta.sh API calls are simple HTTP requests, which must include an OAuth 2.0 token either as an HTTP header (see the OAuth 2.0 spec for details) or as the token form field.

Once the POST request completes, the Sta.sh API returns either a 401 page in case of an OAuth 2.0 authentication failure, or a result in JSON format.

Submit

The submit call accepts one or more files as multipart/form-data.

When authenticated with OAuth 2.0 draft 10:

https://www.deviantart.com/api/draft10/stash/submit

With draft 15:

https://www.deviantart.com/api/draft15/stash/submit
The rest of the form fields are a list of optional key/values. Supported keys are:

title the title of the deviation

artist_comments additional information about the deviation provided by the author. Do not include your application or website's name in that field, it is already automatically credited on the artwork page.

keywords a space-separated list of keywords describing the deviation

original_url link to the original, in case the artwork being submitted is already hosted online. This field can be restricted with a whitelist.

stashid stashid of an existing sta.sh submission, allows to update metadata without having to resubmit the files. Can also be used to overwrite existing files. If you make a new API call containing files, the files that were previously associated with the artwork will be replaced by the new ones.

folder a folder name. This is particularly useful for synchronizing many artworks organized in folders at once. We currently do not support any hierarchy in the folders. If you specify a name that already exists, it will add the new sta.sh item to the existing folder. Users can rename folders in their stash, in order to implement persistent folder sync, use folderid.

folderid a folder id. This is our internal id for folders created through API calls using the "folder" parameter. Since folders are subject to renaming, using folderid allows you to keep track of a folder once created, regardless of what the user renames it to on deviantART's side.


A successful response: {status: "success", stashid: "4502318545176648", folder: "Awesome Artworks", folderid: "123456"} If you are performing an update to a stash item that has been submitted to deviantART, the response format would be: {status: "success", stashid: "4502318545176648"}

Once you have received a successful JSON result containing a stashid, the artwork becomes available at the following URL: http://sta.sh/14502318545176648 Where "4502318545176648" is the stashid you've received. Be careful that the 1 directly following sta.sh/ is not part of the id.

You can also generate the shorter canonical link with the following format (recommended):

http://sta.sh/018bxsl3dm4o Where "18bxsl3dm4o" is the base36-encoded value of the stashid returned by the API (4502318545176648). Be careful that the 0 directly following sta.sh/ is not part of the id.

That short link is very useful for cross-posting immediately to social networks with limited message length.

Move sta.sh submission to another folder

When authenticated with OAuth 2.0 draft 10:

https://www.deviantart.com/api/draft10/stash/move

With draft 15:

https://www.deviantart.com/api/draft15/stash/move
Required form field:

stashid stashid of an existing sta.sh submission.

The rest of the form fields are a list of optional key/values. Supported keys are:

folder a folder name. A new sta.sh folder will be created if one does not already exist with the folder name. The files will then be moved into the folder with this name.

folderid a folder id. Move the sta.sh into the folder with this id. This is our internal id for folders created through API calls using the "folder" parameter.


A successful response: {status: "success", stashid: "4502318545176648", folder: "Awesome Artworks", folderid: "123456"}

Rename folder

The edit call accepts one or more files as multipart/form-data.

When authenticated with OAuth 2.0 draft 10:

https://www.deviantart.com/api/draft10/stash/folder

With draft 15:

https://www.deviantart.com/api/draft15/stash/folder
Required keys:

folder the new name of the folder

folderid a folder id. This is our internal id for folders created through API calls using the "folder" parameter.



A successful response: {status: "success", folder: "Awesome Artworks", folderid: "123456"}

Available space

Check how much sta.sh space the user has left for new uploads. The endpoints are:

https://www.deviantart.com/api/draft10/stash/space
https://www.deviantart.com/api/draft15/stash/space
You must specify an OAuth 2.0 access token when querying the above URLs and you need to call the endpoint that corresponds to the OAuth 2.0 draft you've obtained the access token with.

That API call simply returns the JSON-encoded space value, expressed in bytes: {"available_space":2121102872}

Error values

If the OAuth 2.0 authentication fails, the Sta.sh API returns a 400/401 with an error description that complies with the OAuth 2.0 specification.

If the Sta.sh call itself fails, the error returned is a 400 and can be one of the following values:

{status: "error", error: "invalid_stashid", error_description: "This stashid does not exist"}
{status: "error", error: "application_api_threshold", error_description: "The application has sent a very excessive amount of API calls and is temporarily blocked"}
{status: "error", error: "user_api_threshold", error_description: "The user has sent a very excessive amount of API calls and is temporarily blocked"}
{status: "error", error: "quota_exceeded", error_description: "Upload is too large, user would exceed his/her stash storage quota (X bytes, Y of which are currently used)"}
{status: "error", error: "invalid_access_author", error_description: "Cannot modify this deviation, it does not belong to this user)"}
{status: "error", error: "invalid_access_client", error_description: "Cannot modify this deviation, it wasn't originally submitted through this app)"}
{status: "error", error: "internal_error_missing_folder", error_description: "Unable to create or get folder for stash item"}
{status: "error", error: "internal_error_item", error_description: "Unable to create or update stash item"}
{status: "error", error: "internal_error_missing_metadata", error_description: "Unable to load metadata for folder"}
{status: "error", error: "internal_error_file_corruption", error_description: "Corrupt or incomplete file"}
{status: "error", error: "internal_error_file_too_large", error_description: "File provided is too large"}
{status: "error", error: "internal_error_upload_failure", error_description: "File upload failed"}
{status: "error", error: "invalid_folderid", error_description: "Unable to get folder with that folderid for stash item"}
{status: "error", error: "invalid_access_folder", error_description: "Folder with that folderid does not belong to this user"}