Deviant Login Shop  Join deviantART for FREE Take the Tour

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/oauth2/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 to create and place the new submission in. (Ignored if folderid is set)
  • 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: "Stash Uploads 1",
  folderid: "123456"
}
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/oauth2/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

Move a file into another folder or move file and folder positions. The endpoints are:

https://www.deviantart.com/api/oauth2/stash/move/file
https://www.deviantart.com/api/oauth2/stash/move/folder
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. The file will then be moved into that folder.
  • folderid A folder id.
    The file will be moved into the folder with this id.
  • targetid A folder id.
    When moving a folder this will be the folder that the folder is moved into.
  • position The new position (zero indexed).
    The files position in the stack will be updated to this position. Not this cannot be used in combination with folder and folderid.
Examples

To move a folders position:

Request: 
    folderid=56789&position=5
Response: 
    {
        status: "success",
        folder: "Sta.sh Uploads 1",
        folderid: 56789,
        position: 5
    }

To move a folder into another folder:

Request: 
    folderid=56789&targetid=98765
Response: 
    {
        status: "success",
        folder: "Sta.sh Uploads 1",
        folderid: 98765,
        position: 0
    }

To move a file's position:

Request: 
    stashid=12345&folderid=56789&position=0
Response: 
    {
        status: "success",
        stashid: 12345
        folderid: 56789,
        position: 0
    }

To move a file into new folder:

Request: 
    stashid=12345&folder=My+Great+Folder&position=0
Response: 
    {
        status: "success",
        stashid: 12345
        folder: "My Great Folder"
        folderid: 56789,
        position: 0
    }

To move a file into a existing folder:

Request: 
    stashid=12345&folderid=56789&position=0
Response: 
    {
        status: "success",
        stashid: 12345
        folder: "My Great Folder"
        folderid: 56789,
        position: 0
    }

Rename Folder

Rename a Sta.sh folder. The endpoints are:

https://www.deviantart.com/api/oauth2/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/oauth2/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/oauth2/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
  • ext_submission Include extended submission information, see /metadata
  • ext_camera Include extended camera EXIF information, see /metadata
  • ext_stats Include extended statistics, see /metadata
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.
    • position An integer representing the position of the position of the item in the user's Sta.sh (for folders) or within it's folder (for sta.sh submissions).
      The meaning of this field changes depending on whether or not a cursor has been sent with the call. For calls that do not include a cursor, it indicates the absolute position of the item, starting from zero. In this case, the position will be present for every item.
      For calls that do include a cursor, the position field indicates a relative change of position. Values can be either positive for movement toward the end of the list or negative for movement toward the beginning of the list. If there have been no position changes to the item, then the position field will not be present.
      Relative position changes only reflect explicit changes, i.e. the user specifically moving that item. They do not account for the implicit change in position when an item is added or deleted earlier in the list. Your app is responsible for taking those into account and calculating the absolute positions accordingly. In order to do that correctly, your app will need to evaluate the entries in the order in which they are returned.
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: [
    {
      folderid: 5678,
      metadata: { ... },
      position: 0
    },
    {
      stashid: 1234,
      folderid: 5678,
      metadata: { ... },
      position: 0
    },
    {
      stashid: 2345,
      folderid: 5678,
      metadata: { ... },
      position: 1
    },
    {
      stashid: 3456,
      folderid: 5678,
      metadata: { ... },
      position: 2
    }
  ]
}

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 user moves the submission with id 3456 to be the first item in the folder, the response will indicate the position change like this:

{
  cursor: 'fa7b7b5584d3a0c88e67978a33c47971',
  has_more: false,
  reset: false,
  entries: [
    {
      stashid: 3456,
      folderid: 5678,
      metadata: { ... },
      position: -2
    }
  ]
}

The position of -2 indicates that the item has been moved two positions closer to the beginning of folder. Note that the response still contains the full current /metadata. This is because an entry with a position update can also encompass changes to metadata. It is your app's job to figure out if the metadata needs updating, or just the position.

If the submission with id 1234 is then deleted by the user, the next call to /delta with the updated cursor (fa7b7b5584d3a0c88e67978a33c47971) 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, move and delete), the response would look like:

{
  cursor: '77e07622173ff206bf5962da46ee0ad9',
  has_more: false,
  reset: false,
  entries: [
    {
      stashid: 3456,
      folderid: 5678,
      metadata: { ... },
      position: -2
    },
    {
      stashid: 1234,
      folderid: null,
      metadata: null
    }
  ]
}

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

Note that the position change to the submision with stashid 3456 is reported first. To correctly calculate the final positions of the folder contents, your app must account for these changes in order. That is, move submission 3456 two places earlier and then remove submission 1234. Performing those updates in a different order can cause positions to get out of sync.

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/oauth2/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)
  • ext_submission Include extended submission information (defaults to false)
  • ext_camera Include extended camera EXIF information (defaults to false)
  • ext_stats Include extended statistics (defaults to false)
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 requesting extended information, 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", 
  creation_time: "1373976135", 
  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"
  }, 
  submission: {
    file_size: "6.0 MB", 
    resolution: "4608x3456", 
    submitted_with: {
      app: "Sta.sh", 
      url: "http://sta.sh"
    }
  }, 
  camera: {
    make: "Panasonic", 
    model: "DMC-FS35", 
    shutter_speed: "10/80 second", 
    aperture: "F/4.1", 
    focal_length: "11 mm", 
    iso_speed: "1600", 
    date_taken: "Jun 8, 2012, 12:52:03 PM", 
    software: "Ver.1.0 ", 
    orientation: "1"
  }, 
  stats: {
    views: 32067, 
    views_today: 12430, 
    downloads: 17654, 
    downloads_today: 99332
  }
}

The camera keys can be any valid EXIF key

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",
  parentid: 1234
  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.

The parentid key is the folderid of the folder containing the current one. If parentid is absent, the folder is at the root.

Fetch Submission Media

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

https://www.deviantart.com/api/oauth2/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
{
  error: "invalid_stashid",
  error_description: "This stashid does not exist"
}
{
  error: "application_api_threshold",
  error_description: "The application has sent a very excessive amount of API calls and is temporarily blocked"
}
{
  error: "user_api_threshold",
  error_description: "The user has sent a very excessive amount of API calls and is temporarily blocked"
}
{
  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)"
}
{
  error: "invalid_access_author",
  error_description: "Cannot modify this deviation, it does not belong to this user)"
}
{
  error: "internal_error_missing_folder",
  error_description: "Unable to create or get folder for stash item"
}
{
  error: "internal_error_item",
  error_description: "Unable to create or update stash item"
}
{
  error: "internal_error_missing_metadata",
  error_description: "Unable to load metadata for folder"
}
{
  error: "internal_error_file_corruption",
  error_description: "Corrupt or incomplete file"
}
{
  error: "internal_error_file_too_large",
  error_description: "File provided is too large"
}
{
  error: "internal_error_upload_failure",
  error_description: "File upload failed"
}
{
  error: "invalid_folderid",
  error_description: "Unable to get folder with that folderid for stash item"
}
{
  error: "invalid_access_folder",
  error_description: "Folder with that folderid does not belong to this user"
}