deviant art

Deviant Login Shop
 Join deviantART for FREE Take the Tour

Developers

Stash Your Content with the Sta.sh API

The Sta.sh API enables your app to upload, modify, and manage user content on the Sta.sh platform.

Before making API calls, users must /authorize your app and authenticate with deviantART's OAuth 2.0 API.

When your app calls the Sta.sh API, it provides a specific user's access_token which is obtained in the authentication step by a call to /token. You can provide the access_token as an HTTP header or as an HTTP POST field.

Once the request completes, the Sta.sh API will return a response in JSON format.

Notes
  • In order to help make your app more responsive, we advise developers to always make a /placebo call to check that an access_token is still valid. If the access_token isn't valid, you should then make a /token call to refresh it before making any API call that includes a file.

    When an expired access_token is used in an API call, it will fail with a corresponding error message. If you upload a big file with an expired token, you will only see the potential error response after the entire upload has finished.

  • If an error occurs, the API will return an appropriate HTTP status code.
    For example, HTTP 400 Bad Syntax or HTTP 401 Unauthorized.

Submit

Submit files to Sta.sh or modify existing files. The endpoints are:

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

This call requires one or more files to be sent as multipart/form-data.

It can receive files in any format. Some formats like JPG, PNG, GIF, HTML or plain text can be viewed directly on Sta.sh and deviantART. Other file types are made available for download and may have a preview image.

Required Parameters

These parameters may be sent as POST or GET fields.

  • access_token The token obtained by a call to /token
Optional Parameters

These parameters must be sent as POST fields.

  • title The title of the submission
  • artist_comments Additional information about the submission provided by the author.
    Please do not include your app's name in this field since it will automatically be credited on the artwork page.
  • keywords A space-separated list of keywords describing the submission
  • original_url A link to the original, in case the artwork has already been posted elsewhere.
    This field can be restricted with a whitelist by editing your deviantART app.
  • stashid The id of an existing Sta.sh submission
    This can be used to overwrite files and /metadata of existing submissions. 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 The name of the folder that will contain the submission.
    This is particularly useful for submitting multiple files into a folder. If you specify a name that already exists, it will add the new file to the existing folder. Otherwise it will create a new folder. Users can rename folders in their stash, so use folderid instead if you need to maintain persistence. Folders are non-hierarchical.
  • folderid The id of the folder that will contain the submission.
    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 persistent track of folders even if their names change.
Successful Response
{
  status: "success",
  stashid: "0123456789",
  folder: "Awesome Artwork",
  folderid: "0123456789"
}

If you perform an update to a stash item that has been submitted to deviantART (and is therefore no longer available in Sta.sh), the folder and folderid parameters will not be present

Artwork URLs

When you've received a successful JSON result containing a stashid, the artwork becomes available at a URL like:

http://sta.sh/14502318545176648

Here, 4502318545176648 would be replaced by the actual stashid you've received.
Note that the 1 directly following sta.sh/ is part of the URL, but not part of the id.

We recommend that you generate the shorter canonical link with the following format:

http://sta.sh/018bxsl3dm4o

Here, 18bxsl3dm4o is the base36-encoded value of the stashid returned by the API (example: 4502318545176648).
Note that the 0 directly following sta.sh/ is part of the URL, but not part of the id.

This short link is very useful for posting to social networks with limited message length.

Delete

Delete a previously submitted file. The endpoints are:

https://www.deviantart.com/api/draft10/stash/delete
https://www.deviantart.com/api/draft15/stash/delete
Required Parameters

access_token may be sent via GET or POST, but stashid may only be sent via POST.

  • access_token The token obtained by a call to /token
  • stashid The id of an existing sta.sh submission.
Successful Response
{
  "status": "success",
  "stashid": "0123456789"
}

Move File to Another Folder

Move a previously submitted file from one folder to another. The endpoints are:

https://www.deviantart.com/api/draft10/stash/move
https://www.deviantart.com/api/draft15/stash/move
Required Parameters

access_token may be sent via GET or POST, but stashid must be sent as a POST field.

  • access_token The token obtained by a call to /token
  • stashid The id of an existing sta.sh submission.
Optional Parameters
  • folder A folder name.
    A new Sta.sh folder will be created if one with this name does not exist. The files will then be moved into that folder.
  • folderid A folder id.
    The file will be moved into the folder with this id.
Successful Response
{
  status: "success",
  stashid: "4502318545176648",
  folder: "Awesome Artwork",
  folderid: "123456"
}

Rename Folder

Rename a Sta.sh folder. The endpoints are:

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

access_token may be sent as GET or POST but the other parameters must be sent as POST fields.

  • access_token The token obtained by a call to /token
  • folder The new name of the folder
  • folderid The id of the folder you'd like to rename.
    This is our internal id for folders created through API calls using the folder parameter
Successful Response
{
  status: "success",
  folder: "Awesome Artwork",
  folderid: "123456"
}

Available Space

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

https://www.deviantart.com/api/draft10/stash/space
https://www.deviantart.com/api/draft15/stash/space
Required Parameters

This parameter may be sent as either a GET or POST field.

  • access_token The token obtained by a call to /token
Successful Response

This call returns JSON-encoded space values, expressed in bytes:

{
  "available_space": 2121102872,
  "total_space": 10605514360
}

List Folders and Submissions

Retrieve a list of all Sta.sh folders and submissions for a user. The endpoints are:

https://www.deviantart.com/api/draft10/stash/delta
https://www.deviantart.com/api/draft15/stash/delta

This API call is incremental. The first time you call it for a user, your app will receive the full list of that user's Sta.sh folders and submissions. Your app should cache these results locally.

Afterward, your app should then provide a cursor parameter for all /delta calls. This cursor tells us which data you have already received so that we can send you only new and modified folders and submissions.

Required Parameters

This parameter may be sent as either a GET or POST field.

  • access_token The token obtained by a call to /token
Optional Parameters

The following parameters may be sent as GET or POST fields.

  • cursor The cursor hash provided to your app in the last delta call
  • offset The offset provided to your app if the last delta call returned too many results
Successful Response
  • cursor A unique hash representing the current state of a user's Sta.sh.
    This should be recorded and passed back as the cursor parameter during the next /delta request for this user.
  • has_more A boolean indicating whether or not your app should call /delta again to get the remaining results.
    The repeat delta call should use the same cursor (empty if none was provided) and the next_offset value.
  • next_offset An integer offset which should be passed back during the next /delta call to get the remaining results.
    This is only necessary if has_more is set to true.
  • reset A boolean indicating whether your app should reset its local cache to the returned state (as opposed to updating based on it)
  • entries An array of delta entry objects, each containing the following structure:
    • stashid The id of an existing sta.sh submission. (not present for folders)
    • folderid If stashid is present, this will be the folderid of the submission's containing folder.
      If stashid is omitted, this will be the folderid of a modified folder.
    • metadata An object representing the item's metadata. This object is in the same format as the result of the /metadata API call (except that folders will never have a contents key).
      If this value is null, the item has been deleted.
Example

After authenticating, your app should make a /delta API call.

This will return JSON data similar to the following:

{
  cursor: '366d90716db162067d08775c20f72abe',
  has_more: false,
  reset: false,
  entries: [
    {
      stashid: 1234,
      folderid: 5678,
      metadata: { ... }
    },
    {
      stashid: 2345,
      folderid: 5678,
      metadata: { ... }
    },
    {
      folderid: 5678,
      metadata: { ... }
    }
  ]
}

This represents the complete state of a user's Sta.sh (possibly a section of the complete state if has_more = true).

Your app should cache this information locally along with the cursor value.
Note that cursor is an opaque value. Your app shouldn't care what the value is - only if it's changed.

When your app next makes a /delta call, it should pass the cursor obtained by the last /delta call.

If nothing has changed on the server, the response will look like this:

{
  cursor: '366d90716db162067d08775c20f72abe',
  has_more: false,
  reset: false,
  entries: []
}

Now suppose that the user changes some /metadata of a submission with id 1234.
The response to the next /delta call would look like this:

{
  cursor: '175c1610ba487338c1ba1aa7a979a211',
  has_more: false,
  reset: false,
  entries: [
    {
      stashid: 1234,
      folderid: 5678,
      metadata: { ... }
    }
  ]
}

Though omitted for brevity here, metadata would represent the full set of current /metadata for that submission.
Differences in individual metadata keys are not reported.
It is your app's responsibility to figure out how the new information differs from your local cache and to update accordingly.

If the submission with id 1234 is then deleted by the user, the next call to /delta with the updated cursor (175c1610ba487338c1ba1aa7a979a211) will return a response that looks like this:

{
  cursor: '77e07622173ff206bf5962da46ee0ad9',
  has_more: false,
  reset: false,
  entries: [
    {
      stashid: 1234,
      folderid: null,
      metadata: null
    }
  ]
}

The null metadata indicates that the submission with id 1234 has been deleted.

Note that deltas represent state differences. They are not a full replay log of all changes.

If there have been any number of updates to the cursor since your app last checked, the /delta call will only return the overall difference from the last retrieved state.

So if your app made a /delta call with the cursor 366d90716db162067d08775c20f72abe (which is the cursor from before the update and delete), the response would look like:

{
  cursor: '77e07622173ff206bf5962da46ee0ad9',
  has_more: false,
  reset: false,
  entries: [
    {
      stashid: 1234,
      folderid: null,
      metadata: null
    }
  ]
}

You can see that this /delta response only reports the final state, i.e. the /delete. The previous update is not reported. Likewise, if there are multiple updates to an item between /delta calls, they will be treated as a single change in the /delta response's entries.

Notes
  • When no cursor is passed, the delta call will return the entire contents of the user's Sta.sh in the entries key.
    When a valid cursor is passed, only items which have changed since that cursor was created will be included.
  • If an invalid cursor is passed, the API will default to returning a full delta and will set the reset parameter to true. This can happen if we have updated our API since the last /delta call, or if there are too many changes since the cursor was created.
  • If a submission or folder is present within entries, it means that some property of the submission or folder has changed and your app should update its local cache to reflect the new information returned in the metadata. If the metadata is null, it means that the corresponding submission or folder has been deleted.
  • If the entries key is empty, it means that no items have changed.

Fetch Folder or Submission Metadata

Retrieve the metadata for a Sta.sh folder or submission. The endpoints are:

https://www.deviantart.com/api/draft10/stash/metadata
https://www.deviantart.com/api/draft15/stash/metadata
Required Parameters

access_token may be sent as a GET or POST field, but stashid and folderid must be sent as POST fields.

  • access_token The token obtained by a call to /token
  • stashid Fetch metadata for the submission with this id
    Only required retrieve a Sta.sh submission
  • folderid Fetch metadata for the submission with this folderid
    Only required to retrieve a Sta.sh folder
Optional Parameters

This parameter may be sent as either a GET or POST field.

  • list Include the contents of the folder (defaults to true)
Successful Response

When passed a stashid, the response is a JSON object with the following keys:

{
  stashid: 1234,
  folderid: 5678,
  is_folder: false,
  title: "My Awesome Deviation",
  artist_comments: "The secret ingredient is soylent green.",
  keywords: "soylent green is people",
  original_url: "",
  category: "customization/skins",
  files: {
    original: "http://fc07.deviantart.net/example.png",
    fullview: "http://fc07.deviantart.net/example.png",
    "150":    "http://th08.deviantart.net/example.png",
    "200H":   "http://th00.deviantart.net/example.png",
    "300W":   "http://th00.deviantart.net/example.png"
  }
}

The files key is an object containing URLs of this submission's original file and thumbnails. The available URLs vary by submission type.


When passed a folderid, the response is a JSON object with the following keys:

{
  folderid: 5678,
  is_folder: true,
  title: "Collection of Stuff",
  description: "A wonderful collection of Sta.shy stuff",
  size: 1,
  thumb: "http://fc07.deviantart.net/example.png",
  contents: [ ... ]
}

The thumb key represents the URL of the thumbnail used by this folder and may not be set in the response.

The contents key is an array of the items contained in the folder. Each item in contents is an object with the same structure as that which is returned by this call when made with a stashid. This key is omitted if the list parameter is set to false.

Fetch Submission Media

Retrieve the original media associated with a Sta.sh submission. The endpoints are:

https://www.deviantart.com/api/draft10/stash/media
https://www.deviantart.com/api/draft15/stash/media
Required Parameters

These parameters may be sent as either GET or POST fields.

  • access_token The token obtained by a call to /token
  • stashid Fetch media for the submission with this id
Successful Response
{
  url: "http://fc07.deviantart.net/fs71/f/2012/188/d/8/test_by_zombiecoder-d56by34.png",
  size: 4913,
  width: 640,
  height: 400
}

Errors

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

If the Sta.sh call itself fails, it returns an HTTP 400 and the corresponding JSON error can be one of the following values:

Error 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: "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"
}