• 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.

These parameters may be sent as POST or GET fields.

• access_token The token obtained by a call to /token

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.

{
  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

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

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:

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.

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.

{
  "status": "success",
  "stashid": "0123456789"
}

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.

• 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.

{
  status: "success",
  stashid: "4502318545176648",
  folder: "Awesome Artwork",
  folderid: "123456"
}

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

{
  status: "success",
  folder: "Awesome Artwork",
  folderid: "123456"
}

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

• access_token The token obtained by a call to /token

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

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

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

• access_token The token obtained by a call to /token

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

• 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.

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.

• 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.

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

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

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

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.

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

{
  url: "http://fc07.deviantart.net/fs71/f/2012/188/d/8/test_by_zombiecoder-d56by34.png",
  size: 4913,
  width: 640,
  height: 400
}

{
  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"
}