API Documentation

Computers talking to computers.
Let the fun begin!

Welcome

This is where the fun begins. Time for you to get familiar with the new Envato Market API. You'll find here all the documentation, from basic information to the how-tos and the beloved lines of code. That's all you need to start playing around with our API, unlock the superpowers, release the kraken, hack away.

The Basics

What is an API?

See up there, where we say "Computers talking to computers"? That's kind of the TL;DR version of what an API is. The acronym stands for Application Programming Interface. Want to build an app that can access the data and/or features of another application? An API is a set of procedures and functions that will allow you to do so.

What do we mean by "app"?

You guessed it - Envato Market has an API. This means you can build an app that hooks into Envato Market via the API and accesses account data (such as sales count) and/or features (such as search) - and makes life easier for you and potentially millions of users! This could be a mobile app, a website, or any single service that allows users to access Envato Market's resources.

What services are available?

Here is a list of the data and features you can access via the API. Stay tuned for more!

Discovering content. You can access all resources available on Envato Market, including:

  • The item and comment search feature, with all of our new facets and filtering options;
  • Details on authors and their items;
  • Public collections (as well as your private ones).

Account information. This includes:

  • Your account details, including your balance;
  • Your purchases: you'll be able download the items you've recently bought;
  • Your sales: including verifying purchase codes of items you've sold.

Apps currently available

Want to see some of the apps that our community has already created? Have a look, be amazed!

Get Started

Register your app

You surely hate nasty annoying bots just as much as we do. So you'll understand why we ask you to register every app you create - we want to make sure that our API is only used to build awesome products for our community. It won't take long anyway. We'll ask you to provide a few details including the name and a description of your app, as well as the permissions that the user will need to grant in order to use it. To use the API, you'll need to agree to our API Service Terms and Conditions - we promise that they're friendly and easy to read, so make sure you look them over before you register.

Your application key

Once you've registered your app (and got us super excited because we can't wait to see what you're creating there), you'll get an application key. It's a unique code that allows you to connect with our API. You can always find all your registered applications in the "Manage your apps" page. Remember to keep the key secret - you don't want other people to use the API on your behalf!

If you're not going to build an app that requires useres to log in, and want to access the API directly yourself, you can simply create a personal token.

Authenticating users

With the old API, authentication was a bit of a pain. Users had to go to Envato Market, log in, retrieve an API key and then copy-paste it into your app. Not anymore! With the new API, users will be redirected from your app to a login page that we will provide, and once they have successfully logged in we'll send them back to the app. If it's the first time they've logged in to your app, they will also have to grant the permissions your app requires.

You can find more detailed info about the whole OAuth flow below.

Share your work

Once you've created your app, you'll sure want to let our community know that there's a new neat product to help them make the most out of Envato Market. Shoot us the link, and we'll showcase it on our Market Blog!

Authenticating with OAuth

The Envato Market API supports the full OAuth authentication flow, so that you can allow users of your app to sign in with their Envato Account in order to access the API on their behalf. Using OAuth authentication is simple:

First, register your application so that users know which permissions your app needs. Make a note of the secret application key, and OAuth client ID, that you'll be given during registration - they'll come in handy.

Before your app accesses the Envato API, you'll need to authenticate the user. Your app should redirect the user to the following location:

https://api.envato.com/authorization?response_type=code&client_id=[CLIENT ID]&redirect_uri=[REDIRECT URI]

You can replace [CLIENT ID] with the OAuth Client ID of your app from the My Apps page, and [REDIRECT URI] with the fully-qualified URL you'd like to send the user back to once authentication is successful (this must match the Confirmation URL setting configured when you created your app - you can edit it from the above page).

After the user has logged in and given their permission, the Envato API will redirect them back to your application on the Confirmation URL provided, with a single-use authentication code provided in the query string (eg. http://your.app/callback?code=abc123...). You must use this code to request an access token from the API, by sending the following POST request from your server (encoded as application/x-www-form-urlencoded), replacing [CODE] with the code you've just received, [CLIENT_SECRET] with your secret application key, and the other fields as necessary:

POST https://api.envato.com/token?grant_type=authorization_code&code=[CODE]&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]

The server will respond with an access token:

{
  "refresh_token": "GBdxWsxo1CqAK9yCneH75wgkXw1q7bio",
  "token_type": "bearer",
  "access_token": "c0lQ2WLYW9qAZ9RH12cH1fJPzVWSscXP",
  "expires_in": 3600
}

You can use the access token, which is valid for up to an hour, to make requests to the API on behalf of the logged-in user, by adding it as a bearer token to the Authorization header on any subsequent requests:

curl -H "Authorization: Bearer c0lQ2WLYW9qAZ9RH12cH1fJPzVWSscXP" https://api.envato.com/v1/market/private/user/account.json

{
  "account": {
    "image": "https://0.s3.envato.com/files/100000009/0006893824_192.jpg",
    "firstname": "Test",
    "surname": "User",
    "available_earnings": "0.00",
    "total_deposits": "0.00",
    "balance": "0.00",
    "country": "Australia"
  }
}

After the one-hour period is up and the access token has expired, you can continue using the API on the user's behalf with the refresh token that was originally returned. You can use the refresh token to request a new, valid access token with the request below, and then use it for subsequent requests to the API:

POST https://api.envato.com/token grant_type=refresh_token& refresh_token=[REFRESH_TOKEN]& client_id=[CLIENT_ID]& client_secret=[CLIENT_SECRET]

The server will respond with a new access token:

{
  "token_type": "bearer",
  "access_token": "x0lQ2WLYW9qAZ9RH12cH1fJPzVWSscXZ",
  "expires_in": 3600
}

Note: the Envato API also supports the alternate, implicit OAuth authentication flow, if you are developing a browser-based app and don't wish to include the application's secret key in a place where it could be read by users.

Authenticating with a Personal Token

It may be that your app doesn't require to assume the role of a third-party user to access the Envato API - for example, if your app just accesses public data, such as performing searches for items on Envato Market. In this situation, rather than the complication of implementing OAuth and requiring users to log in and grant permissions to your app, you can simply generate a personal token, and then insert it directly into the authorization header on any API requests:

curl -H "Authorization: Bearer oVi4yPxk1bJ64Y2qOsLJ2D2ZlC3FpK4L" https://api.envato.com/v1/market/total-items.json

{
  "total-items": {
    "total_items": "7411418"
  }
}

Rate Limiting

All requests to the Envato API are dynamically rate limited. As such are unable to provide static values as these will vary between clients. To determine when we enforce these rate limits we use a combination of factors, including, but not limited to:

  • Number of previously made requests
  • Requested endpoint (some requests require more resources than others so we limit these more tightly)
  • Client IP reputation
If you do manage to cross the acceptable number of requests you are permitted to make, you will receive a HTTP 429 response. Included in this response is a HTTP header Retry-After that will denote in seconds how long you have to wait until you're able to make requests again. It's important that if you're building automated systems to make requests on your behalf, that you take this into account and handle this scenario gracefully in your application.

API Method Listing

You can find below a list of all the different operations that are currently available on the Envato Market API. Feel free to log in and try them out by filling in the parameters as required, and clicking on "Try it out!"