Stocksy API API Reference

This is the Stocksy API for searching, listing, and purchasing assets (images and videos). All of our endpoints require a Stocksy API Key. For more information on how to acquire an API key, please review our Quickstart Guide at https://www.stocksy.com/docs/api-quickstart/index.html

The sandbox api can be accessed at https://sandbox-api.stocksy.com. If you are using one of our official SDK clients, you will need to change the endpoint to https://api.stocksy.com once you are confident that your code is ready for production.

API Endpoint
https://api.stocksy.com/
Terms of Service: https://stocksy.com/legal/terms/
Contact: [email protected]
Schemes: https
Version: 1.2

Authentication

sigv4

type
apiKey
name
Authorization
in
header
x-amazon-apigateway-authtype
awsSigv4

api-key

type
apiKey
name
x-api-key
in
header

search

Use this endpoint to search for assets by keywords using the 'query' parameter. You can refine your search by leveraging the other parameters. The endpoint responds with a paginated list of assets that match your search. If you want more information about any of the assets returned by the search, such as which sizes are available for that asset, you can use their ids to look them up individually using the assets endpoint. Once you have decided on the asset and size option that works best for you, you can purchase it via the purchases endpoint.

search

Search for assets

GET /search
query: string[]
in query

The query is a comma separated array of strings. Each string is a keyword or phrase that will define and narrow the search results.

Array values passed separated by comma: ?query=aaa,bbb
limit: integer 200
in query

Limit is used to restrict the number of assets returned per page. Default: 200. Maximum: 500 per page.

Array values passed separated by comma: ?limit=aaa,bbb
page: integer 1
in query

Page is used to identify the starting point from which to return results. Page=1 means results 1-100. Page=2 means results 101-200. This example assumes the limit is 100. The number of results returned per page can be altered using the 'limit' parameter.

Array values passed separated by comma: ?page=aaa,bbb
sort: string
in query

Sort is used to organize the result set by the given value. All sorts preserve the search keywords, and results will still be relevant to your initial search. They are simply different ways of sorting the same initial result set. Curated: hand-selected assets that we have chosen to highlight will be returned first. Latest: results are ordered by the date they were published, from most recent to oldest. Popular: the most popular assets will appear higher in the result set. Popularity is determined by a number of factors including likes, purchases, and curated status. Emerging: new and unsold assets relevant to your search.

Possible values: sort=curated/latest/popular/emerging

Array values passed separated by comma: ?sort=aaa,bbb
safe_search: boolean false
in query

If set to true, the search will only return assets that do not contain mature or nsfw content. Please keep in mind that our contributors do their best to tag their own content, but there may be occasional omissions.

Array values passed separated by comma: ?safe_search=aaa,bbb
facet_contenttype: string[]
in query

Facets (filters) help to specify which of the found assets to return. This facet can be used to return specific types of content, such as only videos, or only photos.

Possible values: facet_contenttype=photo_creative/video_creative/all_types

Array values passed as multiple parameters: ?facet_contenttype=aaa&facet_contenttype=bbb
facet_mobile: boolean false
in query

Facets (filters) help to specify which of the found assets to return. If true: return only assets that were shot on a mobile device. If false: results will not be filtered or altered in any way.

Array values passed separated by comma: ?facet_mobile=aaa,bbb
facet_film: boolean false
in query

Facets (filters) help to specify which of the found assets to return. If true: return only assets that were shot on film. If false: results will not be filtered or altered in any way.

Array values passed separated by comma: ?facet_film=aaa,bbb
facet_composition: string[]
in query

Facets (filters) help to specify which of the found assets to return. Composition describes how the photo looks, mainly the distance at which the photo was taken. Distances that are selected will be included. If any distance is selected, all other distances that are not also in the facet_composition array will be excluded. If parameter is not set, by default all photo distances will be returned. Not applicable for video assets.

Possible values: facet_composition=long/medium/close/macro

Array values passed separated by comma: ?facet_composition=aaa,bbb
facet_ungradedvideo: boolean false
in query

Facets (filters) help to specify which of the found assets to return. If true: return only videos that are ungraded. If false: results will not be filtered or altered in any way. Not applicable for photo assets, therefore facet_contenttype=video_creative is implied with this parameter.

Array values passed separated by comma: ?facet_ungradedvideo=aaa,bbb
facet_4kvideo: boolean false
in query

Facets (filters) help to specify which of the found assets to return. If true: return only videos that are 4k. If false: results will not be filtered or altered in any way. Not applicable for photo assets, therefore facet_contenttype=video_creative is implied with this parameter.

Array values passed separated by comma: ?facet_4kvideo=aaa,bbb
facet_orientation: string[]
in query

Facets (filters) help to specify which of the found assets to return. Orientations describe an asset's aspect ratio, where ratio is the length of each side. Orientations that are selected will be included. If any orientation is selected, all other orientations that are not also in the facet_orientation array will be exluded. If parameter is not set, by default all asset orientations will be returned.

Possible values: facet_orientation=tall/horizontal/square/panorama

Array values passed separated by comma: ?facet_orientation=aaa,bbb
200 OK
SearchResult

successful operation

400 Bad Request

Invalid search parameters

Response Example (200 OK) 
{
  "request": {
    "filters": {
      "text": "dog, beach",
      "searchAccess": "public",
      "cameraType": [
        "mobile"
      ],
      "assetType": [
        "video_creative"
      ],
      "page": 1,
      "pageSize": 200,
      "sort": "curated"
    },
    "page": 1,
    "pageSize": 200,
    "sort": "curated"
  },
  "response": {
    "returnedItemCount": 200,
    "totalItemCount": 5890,
    "totalPageCount": 29,
    "items": [
      {
        "id": 1103358,
        "contributor_name": "Ada Lovelace",
        "contributor_id": 1234,
        "title": "Cool lady with her dog",
        "type": "video_creative",
        "orientation": "Horizontal",
        "mature": true,
        "original_dimensions": {
          "height": 1350,
          "width": 1500
        },
        "thumbnail_dimensions": {
          "height": 1350,
          "width": 1500
        },
        "thumbUrl": "https://c.stocksy.com/a/pic400/z0/1102163.jpg",
        "videoDuration": 3.625,
        "videoThumbUrl": "https://c.stocksy.com/a/pic400/y0/1102163.mp4"
      }
    ]
  },
  "userId": 1234,
  "status": "success",
  "message": "successful search"
}
api-key

assets

Use this endpoint to retrieve additional information about a given asset using its id. This endpoint will return all the information we have about that asset, including that asset's availableProducts (this is a list of all sizes, as well as all extended licenses that are available for the asset you looked up). To buy the asset, please remember the productTypeIds of the sizes and/or licenses that you wish to purchase, and submit them to the purchases endpoint. The productTypeIds are found within the availableProducts array. For a more detailed description of productTypeIds and purchasing, please see our Quickstart Guide here: https://www.stocksy.com/docs/api-quickstart/

assets

View asset information by ID

GET /assets/{assetId}
assetId: integer
in path

The ID of the asset in question

200 OK
Asset

OK

401 Unauthorized

Unauthorized

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": 12345,
  "title": "Desert Sunset",
  "description": "A panorama view of the desert at Sunset, New Mexico, USA",
  "matureContent": false,
  "creationDate": "2016-07-22T11:53:37.000Z",
  "contributor_name": "Ada Lovelace",
  "contributor_id": 1234,
  "type": "photo_creative",
  "orientation": "Horizontal",
  "original_dimensions": {
    "width": 3000,
    "height": 2000
  },
  "thumbnail_dimensions": {
    "width": 300,
    "height": 200
  },
  "thumbUrl": "https://c.stocksy.com/a/pic400/z0/1102163.jpg",
  "videoDuration": 0,
  "keywords": [
    "desert",
    "sunset",
    "cactus",
    "nature",
    "sky"
  ],
  "imageCompUrl": "http://url.to/image",
  "availableProducts": [
    {
      "productTypeId": 1,
      "type": "deliverable",
      "name": "Small",
      "description": "A royalty free license that is somewhat petite. 15 USD",
      "price": {
        "amount": 1500,
        "code": "usd",
        "decimals": 2
      },
      "dimensions": {
        "width": 800,
        "height": 600
      }
    },
    {
      "productTypeId": 2,
      "type": "deliverable",
      "name": "Medium",
      "description": "A royalty free license that is more medium in nature. 30 USD",
      "price": {
        "amount": 3000,
        "code": "usd",
        "decimals": 2
      },
      "dimensions": {
        "width": 2000,
        "height": 1500
      }
    },
    {
      "productTypeId": 3,
      "type": "deliverable",
      "name": "Large",
      "description": "A royalty free license that is larger than life. 75 USD",
      "price": {
        "amount": 7500,
        "code": "usd",
        "decimals": 2
      },
      "dimensions": {
        "width": 3000,
        "height": 2000
      }
    }
  ],
  "purchasedProducts": [
    {
      "assetId": 12345,
      "productTypeId": 2,
      "id": 6867571,
      "customerId": 6,
      "customerAgentId": 6,
      "purchaseDate": "2018-05-14T23:06:24.000Z",
      "type": "deliverable",
      "name": "Medium",
      "downloadAt": "/downloads/6867571"
    }
  ],
  "status": "success",
  "message": "Asset retrieved"
}
api-key
sigv4
assets

View information for a collection of assets

GET /assets/index
multifind: integer[]
in query

A list of assetIds

200 OK
Assets

OK

401 Unauthorized

Unauthorized

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": 12345,
    "title": "Desert Sunset",
    "description": "A panorama view of the desert at Sunset, New Mexico, USA",
    "matureContent": false,
    "creationDate": "2016-07-22T11:53:37.000Z",
    "contributor_name": "Ada Lovelace",
    "contributor_id": 1234,
    "type": "photo_creative",
    "orientation": "Horizontal",
    "original_dimensions": {
      "width": 3000,
      "height": 2000
    },
    "thumbnail_dimensions": {
      "width": 300,
      "height": 200
    },
    "thumbUrl": "https://c.stocksy.com/a/pic400/z0/1102163.jpg",
    "videoDuration": 0,
    "keywords": [
      "desert",
      "sunset",
      "cactus",
      "nature",
      "sky"
    ],
    "imageCompUrl": "http://url.to/image",
    "availableProducts": [
      {
        "productTypeId": 1,
        "type": "deliverable",
        "name": "Small",
        "description": "A royalty free license that is somewhat petite. 15 USD",
        "price": {
          "amount": 1500,
          "code": "usd",
          "decimals": 2
        },
        "dimensions": {
          "width": 800,
          "height": 600
        }
      },
      {
        "productTypeId": 2,
        "type": "deliverable",
        "name": "Medium",
        "description": "A royalty free license that is more medium in nature. 30 USD",
        "price": {
          "amount": 3000,
          "code": "usd",
          "decimals": 2
        },
        "dimensions": {
          "width": 2000,
          "height": 1500
        }
      },
      {
        "productTypeId": 3,
        "type": "deliverable",
        "name": "Large",
        "description": "A royalty free license that is larger than life. 75 USD",
        "price": {
          "amount": 7500,
          "code": "usd",
          "decimals": 2
        },
        "dimensions": {
          "width": 3000,
          "height": 2000
        }
      }
    ],
    "purchasedProducts": [
      {
        "assetId": 12345,
        "productTypeId": 2,
        "id": 6867571,
        "customerId": 6,
        "customerAgentId": 6,
        "purchaseDate": "2018-05-14T23:06:24.000Z",
        "type": "deliverable",
        "name": "Medium",
        "downloadAt": "/downloads/6867571"
      }
    ],
    "status": "success",
    "message": "Asset retrieved"
  }
]
api-key
sigv4

purchases

Use this endpoint to purchase products. By this point you will probably want to have already looked up the asset you wish to purchase by its id using the assets endpoint so that you can be certain you are buying the size and/or license that you want. When you purchase any size of an asset, it comes with a royalty-free license by default. If you require a different license, such as 'products for resale', then you will have to find out the productTypeId for that license and then add that into your purchase. A complete list of productTypeIds for both sizes and licenses for any given assetId can be found in the response from the asset endpoint. For more information about the licenses we offer please see the following link: https://www.stocksy.com/service/pricing/ or, for a more detailed description of productTypeIds and purchasing, please see our quickstart guide here: https://www.stocksy.com/docs/api-quickstart/

purchases

Purchase products

POST /purchases
PurchaseRequest

the purchase request

Request Content-Types: application/json
Request Example
{
  "project": "Ad Campaign for North America",
  "client": "Tasty Cola Corporation",
  "poNumber": "ABC-123",
  "products": [
    {
      "assetId": 123,
      "productTypeIds": [
        3,
        8
      ]
    },
    {
      "assetId": 456,
      "productTypeIds": [
        2
      ]
    }
  ]
}
200 OK
PurchaseRequestResponse

OK

401 Unauthorized

Unauthorized

Response Content-Types: application/json
Response Example (200 OK) 
{
  "status": "string",
  "completionUrl": "string",
  "purchase": {
    "id": "integer",
    "customerId": "integer",
    "customerAgentId": "integer",
    "creationDate": "string",
    "status": "string",
    "client": "string",
    "project": "string",
    "poNumber": "string",
    "products": [
      {
        "id": 6867571,
        "assetId": 12345,
        "productTypeId": 2,
        "type": "deliverable",
        "name": "Medium",
        "customerId": 6,
        "customerAgentId": 6,
        "purchaseDate": "2018-05-14T23:06:24.000Z",
        "downloadAt": "/downloads/6867571"
      }
    ],
    "amounts": {
      "subtotal": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "tax": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "total": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "paymentFromAccount": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "paymentFromPayin": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      }
    }
  },
  "category": "string",
  "message": "string"
}
api-key
sigv4
purchases

View your account's previous purchases

GET /purchases
Range: string
in header

Range is a 'Standard HTTP Request Field' which lives in the header. It is optional. Range limits the result set to the requested items. Example: 'items=0-9' returns the first 10 entries.

200 OK
Purchase

a list of previous purchases

type
Purchase
401 Unauthorized

Unauthorized

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "integer",
    "customerId": "integer",
    "customerAgentId": "integer",
    "creationDate": "string",
    "status": "string",
    "client": "string",
    "project": "string",
    "poNumber": "string",
    "products": [
      {
        "id": 6867571,
        "assetId": 12345,
        "productTypeId": 2,
        "type": "deliverable",
        "name": "Medium",
        "customerId": 6,
        "customerAgentId": 6,
        "purchaseDate": "2018-05-14T23:06:24.000Z",
        "downloadAt": "/downloads/6867571"
      }
    ],
    "amounts": {
      "subtotal": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "tax": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "total": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "paymentFromAccount": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "paymentFromPayin": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      }
    }
  }
]
api-key
sigv4
purchases

View purchase information by ID

GET /purchases/{purchaseId}
purchaseId: integer
in path

(no description)

200 OK
Purchase

OK

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "integer",
  "customerId": "integer",
  "customerAgentId": "integer",
  "creationDate": "string",
  "status": "string",
  "client": "string",
  "project": "string",
  "poNumber": "string",
  "products": [
    {
      "id": 6867571,
      "assetId": 12345,
      "productTypeId": 2,
      "type": "deliverable",
      "name": "Medium",
      "customerId": 6,
      "customerAgentId": 6,
      "purchaseDate": "2018-05-14T23:06:24.000Z",
      "downloadAt": "/downloads/6867571"
    }
  ],
  "amounts": {
    "subtotal": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    },
    "tax": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    },
    "total": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    },
    "paymentFromAccount": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    },
    "paymentFromPayin": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    }
  }
}
api-key
sigv4

users

Use this endpoint to get details about your user account, including your id, your available account balance, or the currency you have selected for your purchases and pricing.

users

View your user account information

GET /users
200 OK
User

OK

401 Unauthorized

Unauthorized

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": 6,
  "email": "[email protected]",
  "firstName": "Patrick",
  "lastName": "McGoohan",
  "availableBalance": {
    "amount": 43750,
    "code": "usd",
    "decimals": 2
  }
}
api-key
sigv4

authentication

Use this endpoint to trade your User Account and API Key for temporary IAM Credentials, which are required for all other transactions. For more information, please review our Quickstart Guide here: https://www.stocksy.com/docs/api-quickstart/

authentication

Get temporary IAM credentials for AWSv4 signature protected endpoints

POST /identity
Login

user email address and password

Request Content-Types: application/x-www-form-urlencoded
Request Example
{
  "email": "[email protected]",
  "password": "password123"
}
200 OK
Credentials

OK

Response Content-Types: application/json
Response Example (200 OK) 
{
  "AccessKeyId": "SDF87SDF8S9DFKJSHDFKSJHF",
  "SecretKey": "asdflhsdASDKH09asdf3324+asdfksadjvMNfh",
  "SessionToken": "AgoGsASDfasfasAsdfsd5234SADsdfghgtsdvoiusdv+fsad/arryfgh/akdsfadlsklsasamsdnfakjldshfkasjdhFDgygdndDGuuDgdfbdBDgDYgdfnghfglhkgJKgf////gfgdfl64353FDHdfdgjd",
  "Expiration": "2018-06-27T00:52:20+00:00",
  "status": "success",
  "message": "Login successful"
}
Response Headers (200 OK)
Access-Control-Allow-Origin

undefined

 string
api-key

compdownloads

If you have been granted Comp Download access, use this endpoint to retrieve comp download URLs. If you are interested in getting Comp Download access, please send inquiries to [email protected].

compdownloads

Get comp asset direct download link

GET /compdownloads/{assetId}
assetId: integer
in path

(no description)

200 OK
CompDownloads

OK

401 Unauthorized

Unauthorized

Response Content-Types: application/json
Response Example (200 OK) 
{
  "downloadLink": "https://s3.amazonaws.com/files.stocksy.com/logo-bw.png"
}
api-key
sigv4

downloads

Use this endpoint to retrieve download URLs for purchased products, using the purchasedProduct Id returned from a purchase creation or purchase lookup. If you have purchased multiple images or videos, then each asset will have its own purchasedProduct Id. When executing a purchase at the purchases endpoint, the purchasedProduct Id is returned under the key 'downloadAt' as part of a successful 200 response. If you are trying to re-download something that you bought a long time ago, you can find the purchasedProduct Ids of the assets you are trying to download in your purchase history, at the purchases endpoint.

downloads

Get direct download URL

GET /downloads/{purchasedProductId}
purchasedProductId: integer
in path

(no description)

200 OK
DownloadLink

OK

401 Unauthorized

Unauthorized

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": 12345,
  "url": "https://s3.amazonaws.com/files.stocksy.com/logo-bw.png",
  "expiryDate": "2018-07-19T17:23:05+00:00"
}
Response Headers (200 OK)
Access-Control-Allow-Origin

undefined

 string
api-key
sigv4

Schema Definitions

SearchResult: object

request: SearchRequest
response: SearchResponse
userId: integer
status: string
message: string
Example
{
  "request": {
    "filters": {
      "text": "dog, beach",
      "searchAccess": "public",
      "cameraType": [
        "mobile"
      ],
      "assetType": [
        "video_creative"
      ],
      "page": 1,
      "pageSize": 200,
      "sort": "curated"
    },
    "page": 1,
    "pageSize": 200,
    "sort": "curated"
  },
  "response": {
    "returnedItemCount": 200,
    "totalItemCount": 5890,
    "totalPageCount": 29,
    "items": [
      {
        "id": 1103358,
        "contributor_name": "Ada Lovelace",
        "contributor_id": 1234,
        "title": "Cool lady with her dog",
        "type": "video_creative",
        "orientation": "Horizontal",
        "mature": true,
        "original_dimensions": {
          "height": 1350,
          "width": 1500
        },
        "thumbnail_dimensions": {
          "height": 1350,
          "width": 1500
        },
        "thumbUrl": "https://c.stocksy.com/a/pic400/z0/1102163.jpg",
        "videoDuration": 3.625,
        "videoThumbUrl": "https://c.stocksy.com/a/pic400/y0/1102163.mp4"
      }
    ]
  },
  "userId": 1234,
  "status": "success",
  "message": "successful search"
}

SearchRequest: object

filters: AppliedSearchFilters
page: integer
pageSize: integer
sort: string
Example
{
  "filters": {
    "text": "dog, beach",
    "searchAccess": "public",
    "cameraType": [
      "mobile"
    ],
    "assetType": [
      "video_creative"
    ],
    "page": 1,
    "pageSize": 200,
    "sort": "curated"
  },
  "page": 1,
  "pageSize": 200,
  "sort": "curated"
}

AppliedSearchFilters: object

This section of the response is useful for debugging, and ensuring the facets or filters speficied during the request were in fact applied. The contents of this object may vary depending on which facets or filters you applied to your search request

Example
{
  "text": "dog, beach",
  "searchAccess": "public",
  "cameraType": [
    "mobile"
  ],
  "assetType": [
    "video_creative"
  ],
  "page": 1,
  "pageSize": 200,
  "sort": "curated"
}

SearchResponse: object

returnedItemCount: integer
totalItemCount: integer
totalPageCount: integer
items: SearchAsset
SearchAsset
Example
{
  "returnedItemCount": 200,
  "totalItemCount": 5890,
  "totalPageCount": 29,
  "items": [
    {
      "id": 1103358,
      "contributor_name": "Ada Lovelace",
      "contributor_id": 1234,
      "title": "Cool lady with her dog",
      "type": "video_creative",
      "orientation": "Horizontal",
      "mature": true,
      "original_dimensions": {
        "height": 1350,
        "width": 1500
      },
      "thumbnail_dimensions": {
        "height": 1350,
        "width": 1500
      },
      "thumbUrl": "https://c.stocksy.com/a/pic400/z0/1102163.jpg",
      "videoDuration": 3.625,
      "videoThumbUrl": "https://c.stocksy.com/a/pic400/y0/1102163.mp4"
    }
  ]
}

SearchAsset: object

id: integer
contributor_name: string
contributor_id: integer
title: string
type: string
orientation: string
mature: boolean
original_dimensions: Dimensions
thumbnail_dimensions: Dimensions
thumbUrl: string

For photo assets, this is a preview version of the original image. For video assets, this is a picture of whichever frame was chosen for the thumbnail of the video. The actual video preview can be found under the videoThumbUrl.

videoDuration: number (float)

The duration of the video in seconds. Only returned for video assets.

videoThumbUrl: string

The url of the video preview. The preview is the same duration as the original video, but is of lesser quality and much smaller dimensions. Only returned for video assets.

Example
{
  "id": 1103358,
  "contributor_name": "Ada Lovelace",
  "contributor_id": 1234,
  "title": "Cool lady with her dog",
  "type": "video_creative",
  "orientation": "Horizontal",
  "mature": true,
  "original_dimensions": {
    "height": 1350,
    "width": 1500
  },
  "thumbnail_dimensions": {
    "height": 1350,
    "width": 1500
  },
  "thumbUrl": "https://c.stocksy.com/a/pic400/z0/1102163.jpg",
  "videoDuration": 3.625,
  "videoThumbUrl": "https://c.stocksy.com/a/pic400/y0/1102163.mp4"
}

Asset:

id: integer
contributor_name: string
contributor_id: integer
title: string
description: string
type: string
orientation: string
original_dimensions: Dimensions
thumbnail_dimensions: Dimensions
videoDuration: number (float)

The duration of the video in seconds. Only returned for video assets.

matureContent: string
creationDate: string
keywords: string[]
string
thumbUrl: string

For photo assets, this is a preview version of the original image. For video assets, this is a picture of whichever frame was chosen for the thumbnail of the video. The actual video preview can be found under the videoThumbUrl.

imageCompUrl: string
videoCompUrl: string
availableProducts: AvailableProduct
AvailableProduct
purchasedProducts: PurchasedProduct
PurchasedProduct
status: string
message: string
Example
{
  "id": 12345,
  "title": "Desert Sunset",
  "description": "A panorama view of the desert at Sunset, New Mexico, USA",
  "matureContent": false,
  "creationDate": "2016-07-22T11:53:37.000Z",
  "contributor_name": "Ada Lovelace",
  "contributor_id": 1234,
  "type": "photo_creative",
  "orientation": "Horizontal",
  "original_dimensions": {
    "width": 3000,
    "height": 2000
  },
  "thumbnail_dimensions": {
    "width": 300,
    "height": 200
  },
  "thumbUrl": "https://c.stocksy.com/a/pic400/z0/1102163.jpg",
  "videoDuration": 0,
  "keywords": [
    "desert",
    "sunset",
    "cactus",
    "nature",
    "sky"
  ],
  "imageCompUrl": "http://url.to/image",
  "availableProducts": [
    {
      "productTypeId": 1,
      "type": "deliverable",
      "name": "Small",
      "description": "A royalty free license that is somewhat petite. 15 USD",
      "price": {
        "amount": 1500,
        "code": "usd",
        "decimals": 2
      },
      "dimensions": {
        "width": 800,
        "height": 600
      }
    },
    {
      "productTypeId": 2,
      "type": "deliverable",
      "name": "Medium",
      "description": "A royalty free license that is more medium in nature. 30 USD",
      "price": {
        "amount": 3000,
        "code": "usd",
        "decimals": 2
      },
      "dimensions": {
        "width": 2000,
        "height": 1500
      }
    },
    {
      "productTypeId": 3,
      "type": "deliverable",
      "name": "Large",
      "description": "A royalty free license that is larger than life. 75 USD",
      "price": {
        "amount": 7500,
        "code": "usd",
        "decimals": 2
      },
      "dimensions": {
        "width": 3000,
        "height": 2000
      }
    }
  ],
  "purchasedProducts": [
    {
      "assetId": 12345,
      "productTypeId": 2,
      "id": 6867571,
      "customerId": 6,
      "customerAgentId": 6,
      "purchaseDate": "2018-05-14T23:06:24.000Z",
      "type": "deliverable",
      "name": "Medium",
      "downloadAt": "/downloads/6867571"
    }
  ],
  "status": "success",
  "message": "Asset retrieved"
}

Assets: array

Asset
Example
[
  {
    "id": 12345,
    "title": "Desert Sunset",
    "description": "A panorama view of the desert at Sunset, New Mexico, USA",
    "matureContent": false,
    "creationDate": "2016-07-22T11:53:37.000Z",
    "contributor_name": "Ada Lovelace",
    "contributor_id": 1234,
    "type": "photo_creative",
    "orientation": "Horizontal",
    "original_dimensions": {
      "width": 3000,
      "height": 2000
    },
    "thumbnail_dimensions": {
      "width": 300,
      "height": 200
    },
    "thumbUrl": "https://c.stocksy.com/a/pic400/z0/1102163.jpg",
    "videoDuration": 0,
    "keywords": [
      "desert",
      "sunset",
      "cactus",
      "nature",
      "sky"
    ],
    "imageCompUrl": "http://url.to/image",
    "availableProducts": [
      {
        "productTypeId": 1,
        "type": "deliverable",
        "name": "Small",
        "description": "A royalty free license that is somewhat petite. 15 USD",
        "price": {
          "amount": 1500,
          "code": "usd",
          "decimals": 2
        },
        "dimensions": {
          "width": 800,
          "height": 600
        }
      },
      {
        "productTypeId": 2,
        "type": "deliverable",
        "name": "Medium",
        "description": "A royalty free license that is more medium in nature. 30 USD",
        "price": {
          "amount": 3000,
          "code": "usd",
          "decimals": 2
        },
        "dimensions": {
          "width": 2000,
          "height": 1500
        }
      },
      {
        "productTypeId": 3,
        "type": "deliverable",
        "name": "Large",
        "description": "A royalty free license that is larger than life. 75 USD",
        "price": {
          "amount": 7500,
          "code": "usd",
          "decimals": 2
        },
        "dimensions": {
          "width": 3000,
          "height": 2000
        }
      }
    ],
    "purchasedProducts": [
      {
        "assetId": 12345,
        "productTypeId": 2,
        "id": 6867571,
        "customerId": 6,
        "customerAgentId": 6,
        "purchaseDate": "2018-05-14T23:06:24.000Z",
        "type": "deliverable",
        "name": "Medium",
        "downloadAt": "/downloads/6867571"
      }
    ],
    "status": "success",
    "message": "Asset retrieved"
  }
]

AvailableProduct:

productTypeId: integer
type: string
name: string
description: string
price: CurrencyAmount
dimensions: Dimensions
Example
{
  "productTypeId": 1,
  "type": "deliverable",
  "name": "Small",
  "description": "A royalty free license that is somewhat petite. 15 USD",
  "price": {
    "amount": 1500,
    "code": "usd",
    "decimals": 2
  },
  "dimensions": {
    "width": 578,
    "height": 866
  }
}

Purchase:

id: integer
customerId: integer
customerAgentId: integer
creationDate: string
status: string
client: string
project: string
poNumber: string
products: PurchasedProduct
PurchasedProduct
amounts: PurchaseAmounts
Example
{
  "id": "integer",
  "customerId": "integer",
  "customerAgentId": "integer",
  "creationDate": "string",
  "status": "string",
  "client": "string",
  "project": "string",
  "poNumber": "string",
  "products": [
    {
      "id": 6867571,
      "assetId": 12345,
      "productTypeId": 2,
      "type": "deliverable",
      "name": "Medium",
      "customerId": 6,
      "customerAgentId": 6,
      "purchaseDate": "2018-05-14T23:06:24.000Z",
      "downloadAt": "/downloads/6867571"
    }
  ],
  "amounts": {
    "subtotal": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    },
    "tax": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    },
    "total": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    },
    "paymentFromAccount": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    },
    "paymentFromPayin": {
      "amount": "integer",
      "code": "string",
      "decimals": "integer"
    }
  }
}

PurchaseAmounts:

subtotal: CurrencyAmount
tax: CurrencyAmount
total: CurrencyAmount
paymentFromAccount: CurrencyAmount
paymentFromPayin: CurrencyAmount
Example
{
  "subtotal": {
    "amount": "integer",
    "code": "string",
    "decimals": "integer"
  },
  "tax": {
    "amount": "integer",
    "code": "string",
    "decimals": "integer"
  },
  "total": {
    "amount": "integer",
    "code": "string",
    "decimals": "integer"
  },
  "paymentFromAccount": {
    "amount": "integer",
    "code": "string",
    "decimals": "integer"
  },
  "paymentFromPayin": {
    "amount": "integer",
    "code": "string",
    "decimals": "integer"
  }
}

CurrencyAmount:

amount: integer
code: string
decimals: integer
Example
{
  "amount": "integer",
  "code": "string",
  "decimals": "integer"
}

Dimensions:

height: integer
width: integer
Example
{
  "height": 1350,
  "width": 1500
}

PurchasedProduct:

id: integer
assetId: integer
productTypeId: integer
type: string
name: string
customerId: integer
customerAgentId: integer
purchaseDate: string
downloadAt: string
Example
{
  "id": 6867571,
  "assetId": 12345,
  "productTypeId": 2,
  "type": "deliverable",
  "name": "Medium",
  "customerId": 6,
  "customerAgentId": 6,
  "purchaseDate": "2018-05-14T23:06:24.000Z",
  "downloadAt": "/downloads/6867571"
}

PurchaseRequest:

project: string

Optional field for clients to describe the intended project this purchase is related to.

client: string

Optional field for clients to describe the end client this purchase is related to.

poNumber: string

Optional field for clients to describe the purchase order this purchase is related to.

products: PurchaseRequestProduct

This is an array of asset Id and product type Ids the client wishes to purchase.

PurchaseRequestProduct
Example
{
  "project": "Ad Campaign for North America",
  "client": "Tasty Cola Corporation",
  "poNumber": "ABC-123",
  "products": [
    {
      "assetId": 123,
      "productTypeIds": [
        3,
        8
      ]
    },
    {
      "assetId": 456,
      "productTypeIds": [
        2
      ]
    }
  ]
}

PurchaseRequestProduct:

assetId: integer

The asset Id

productTypeIds: integer[]

Array of one or more product type Ids to buy of this asset. Typical purchases are of a deliverable (small, large) and optionally one or more extended licenses.

integer
Example
{
  "assetId": "integer",
  "productTypeIds": [
    "integer"
  ]
}

PurchaseRequestResponse:

status: string
completionUrl: string
purchase: Purchase
category: string
message: string
Example
{
  "status": "string",
  "completionUrl": "string",
  "purchase": {
    "id": "integer",
    "customerId": "integer",
    "customerAgentId": "integer",
    "creationDate": "string",
    "status": "string",
    "client": "string",
    "project": "string",
    "poNumber": "string",
    "products": [
      {
        "id": 6867571,
        "assetId": 12345,
        "productTypeId": 2,
        "type": "deliverable",
        "name": "Medium",
        "customerId": 6,
        "customerAgentId": 6,
        "purchaseDate": "2018-05-14T23:06:24.000Z",
        "downloadAt": "/downloads/6867571"
      }
    ],
    "amounts": {
      "subtotal": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "tax": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "total": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "paymentFromAccount": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      },
      "paymentFromPayin": {
        "amount": "integer",
        "code": "string",
        "decimals": "integer"
      }
    }
  },
  "category": "string",
  "message": "string"
}

User:

id: integer
firstName: string
lastName: string
email: string
availableBalance: CurrencyAmount
Example
{
  "id": 6,
  "email": "[email protected]",
  "firstName": "Patrick",
  "lastName": "McGoohan",
  "availableBalance": {
    "amount": 43750,
    "code": "usd",
    "decimals": 2
  }
}

Credentials:

AccessKeyId: string
SecretKey: string
SessionToken: string
Expiration: string
status: string
message: string
Example
{
  "AccessKeyId": "SDF87SDF8S9DFKJSHDFKSJHF",
  "SecretKey": "asdflhsdASDKH09asdf3324+asdfksadjvMNfh",
  "SessionToken": "AgoGsASDfasfasAsdfsd5234SADsdfghgtsdvoiusdv+fsad/arryfgh/akdsfadlsklsasamsdnfakjldshfkasjdhFDgygdndDGuuDgdfbdBDgDYgdfnghfglhkgJKgf////gfgdfl64353FDHdfdgjd",
  "Expiration": "2018-06-27T00:52:20+00:00",
  "status": "success",
  "message": "Login successful"
}

Login:

email: string
password: string
Example
{
  "email": "[email protected]",
  "password": "password123"
}

CompDownloads:

downloadLink: string
Example
{
  "downloadLink": "https://s3.amazonaws.com/files.stocksy.com/logo-bw.png"
}
Documentation by Spectacle