Imgur API Version 3

Example code

These examples serve as a starting point to help familiarize you with the basics of the Imgur API.

• Official Python library
• Example Android app
• Example HTML5/JavaScript app—JavaScript OAuth—Live Demo (uses your webcam)
• Example Objective C library

Need help?

Visit the Imgur API Google Group, or reach out on Twitter, @imgurAPI. The API community, as well as the Imgur engineers, are always around answering questions.

Register an Application (IMPORTANT)

Each client must register their application and receive the client_id and client_secret.

For public read-only and anonymous resources, such as getting image info, looking up user comments, etc. all you need to do is send an authorization header with your client_id in your requests. This also works if you'd like to upload images anonymously (without the image being tied to an account), or if you'd like to create an anonymous album. This lets us know which application is accessing the API.

Authorization: Client-ID YOUR_CLIENT_ID

Commercial Usage

Your application is commercial if you're making any money with it (which includes in-app advertising), if plan on making any money with it, or if it belongs to a commercial organization.

To use Imgur's API commercially, you must first register your application. Once that's done, you must register with Mashape. Mashape allows you to choose a pricing plan that fits your needs. From then on, the API endpoint is https://imgur-apiv3.p.mashape.com/ which must be used in replace of https://api.imgur.com/. Additionally, you must set a X-Mashape-Key request header with the key obtained from Mashape.

Free Usage

The Imgur API is free for non-commercial usage. Your application is probably free if you don't plan on making any money with it, or if it's open source.

Heavy Free Usage

If your application is free, but isn't going to work with our rate limiting, then we might be willing to white-list it. Fill out this form submit your white-list request. We will review your request, and if granted, will give you all the access your awesome app desires!

Endpoints

The API is accessed by making HTTP requests to a specific version endpoint URL, in which GET or POST variables contain information about what you wish to access. Every endpoint is accessed via an SSL-enabled HTTPS (port 443), this is because everything is using OAuth 2.0.

Everything (methods, parameters, etc.) is fixed to a version number, and every call must contain one. Different Versions are available at different endpoint URLs. The latest version is Version 3.

The stable HTTP endpoint for the latest version is:

https://api.imgur.com/3/

The previous versions can still be accessed if you use the API version number at the end of the default endpoint. However, these previous versions are no longer supported, so if you find a bug, we're going to ask that you move to the latest version.

Responses

Each response is wrapped in a data tag. This means if you have a response, it will always be within the data field. We also include a status code and success flag in the response. For more information and examples go to the data models page.

Responses are either JSON (the default), JSONP, or XML. Response formats are specified by supplying an extension to the API call. For example, if you want to access the gallery information with JSON:

https://api.imgur.com/3/gallery.json

JSONP responses are made by adding the callback parameter via either GET or POST to the request. For example:

https://api.imgur.com/3/gallery.json?callback=function_name

and to specify an XML response, the URL is:

https://api.imgur.com/3/gallery.xml

Paging Results

For the most part, if the API action is plural, you can page it via a query string parameter.

NOTE: /gallery endpoints do not support the perPage query string, and /album/{id}/images is not paged.

Example:

https://api.imgur.com/3/account/imgur/images/0.json?perPage=42&page;=6

Authentication

The API requires each client to use OAuth 2 authentication. This means you'll have to register your application, and generate an access_code if you'd like to log in as a user.

For public read-only and anonymous resources, such as getting image info, looking up user comments, etc. all you need to do is send an authorization header with your client_id in your requests. This also works if you'd like to upload images anonymously (without the image being tied to an account), or if you'd like to create an anonymous album. This lets us know which application is accessing the API.

Authorization: Client-ID YOUR_CLIENT_ID

For accessing a user's account, please visit the OAuth2 section of the docs.

OAuth Endpoints

To access OAuth, the following endpoints must be used:

• https://api.imgur.com/oauth2/addclient
• https://api.imgur.com/oauth2/authorize
• https://api.imgur.com/oauth2/token

You can also verify your OAuth 2.0 tokens by setting your header and visiting the page https://api.imgur.com/oauth2/secret

Rate Limits

The Imgur API uses a credit allocation system to ensure fair distribution of capacity. Each application can allow approximately 1,250 uploads per day or approximately 12,500 requests per day. If the daily limit is hit five times in a month, then the app will be blocked for the rest of the month. The remaining credit limit will be shown with each requests response in the X-RateLimit-ClientRemaining HTTP header.

If you find you're being rate limited, and your app is completely free (and without ads), then you can submit a request to be white-listed. We ask that you simply fill out this form and we'll let you know if you qualify.

We also limit each user (via their IP Address) for each application, this is to ensure that no single user is able to spam an application. This limit will simply stop the user from requesting more data for an hour. We recommend that each application takes precautions against spamming by implementing rate limiting on their own applications. Each response will also include the remaining credits for each user in the X-RateLimit-UserLimit HTTP header.

Each request contains rate limit information in the HTTP response headers.

Unless otherwise noted, an API call deducts 1 credit from your allocation. However, uploads have a significantly higher computational cost on our back-end, and deduct 10 credits per call. All OAuth calls, such as refreshing tokens or authorizing users, do not deduct any credits.

You can also check the current rate limit status on your application by sending a GET request to https://api.imgur.com/3/credits