API v1

Note: This API is in a beta state. Breaking changes may occur.

This documentation has been heavily inspired by the excellent Github API.

Terms of use

The Desktoppr API can be used for any non-commercial applications. If you wish to use the API for a commercial application, please contact us first.

Our terms are very brief, if you have good intentions then you're more than likely already following them. Here are the details:

• The original copyright holders own all rights to their content and it is your responsibility to make sure your use of the API does not contravene those rights.
• You must remove from your application within 24 hours any wallpaper or personal information that the owner asks you to remove.
• Do not use the name Desktoppr in your application, URL or branding without prior permission.
• Do not use the Desktoppr API for any application that replicates or attempts to replace the essential user experience of desktoppr.co
• If your application derives revenue from its use of the Desktoppr API, it is considered a commercial application. Desktoppr reserves the right to evaluate and monitor commercial applications to ensure that they do not harm Desktoppr's servers or business interests.
• Do not abuse the API or use it excessively. If you're unsure whether your planned use is excessive, ask us.
• Desktoppr may terminate your license to the Desktoppr API under these terms at any time for any reason.
• Desktoppr reserves the right to update and change these terms from time to time without notice.

Schema

All API access is over HTTPS, and accessed from the api.desktoppr.co domain. All data is sent as JSON.

$ curl -i https://api.desktoppr.co
  HTTP/1.1 200 OK
  Server: nginx
  Date: Wed, 02 May 2012 12:27:58 GMT
  Content-Type: application/json; charset=utf-8
  Connection: keep-alive
  Status: 200 OK
  X-Ua-Compatible: IE=Edge,chrome=1
  Etag: "b378f703c80e912313457fdf0f60ca76"
  Cache-Control: max-age=0, private, must-revalidate
  X-Request-Id: 9065d09226cbf357b017cf0dcbce7704
  X-Runtime: 0.007885
  X-Rack-Cache: miss
  Content-Length: 7
  X-Varnish: 1268559407
  Age: 0
  Via: 1.1 varnish

  { "response": "Hello World" }

The Desktoppr API also has JSONP support. Simply add a callback paramater to any API GET request (excluding the whoami endpoint), and it will wrap the response up in a function:

$ curl https://api.desktoppr.co?callback=hello
  hello({
    response: "Hello World"
  })

Authentication

At present, there are only two ways to authenticate against the Desktoppr API:

Basic Authentication:

$ curl -u "username:PASSWORD" https://api.desktoppr.co/1/user/whoami
  {
    "response": {
      "username": "keithpitt",
      "name": "Keith Pitt",
      "avatar_url": "https://...",
      "wallpapers_count": 80,
      "uploaded_count": 200,
      "followers_count": 39,
      "following_count": 76,
      "api_token":"xR4YxRm3yMwo8As4zE6V",
      "created_at": "2012-04-10T11:29:25Z"
    }
  }

Once you have authenticated with username and password, you can use the returned API token for further authenticated requests like so:

Token Authentication:

$ curl https://api.desktoppr.co/1/user/whoami?auth_token=API_TOKEN
  {
    "response": {
      "username": "keithpitt",
      "name": "Keith Pitt",
      "avatar_url": "https://...",
      "wallpapers_count": 80,
      "uploaded_count": 200,
      "followers_count": 39,
      "following_count": 76,
      "created_at": "2012-04-10T11:29:25Z"
    }
  }

Note: You can also find your API token on the user settings page.

Users

To get user information based on a users username

$ curl https://api.desktoppr.co/1/users/keithpitt
  {
    "response": {
      "username": "keithpitt",
      "name": "Keith Pitt",
      "avatar_url": "https://...",
      "wallpapers_count": 80,
      "uploaded_count": 200,
      "followers_count": 39,
      "following_count": 76,
      "created_at": "2012-04-10T11:29:25Z"
    }
  }

To get a paginated list of wallpapers that a user has in their collection

At the moment, we have hard coded the per page setting to be 10. This may change in the future.

$ curl https://api.desktoppr.co/1/users/keithpitt/wallpapers
  {
    "response": [ {
        "id": 380,
        "bytes": 990121,
        "created_at": "2012-04-11T10:33:27Z",
        "image":{
          "url": "http://...",
          "thumb": {
            "url":"http://..."
          },
          "preview": {
            "url":"http://..."
          },
        },
        "height":1080,
        "width":1920,
        "uploader":"mariovisic",
        "user_count":3,
        "palette":[
          "C4C9CA",
          "7D95A1",
          "282827",
          "32515A",
          "636139"
        ]
    } ],
    "count": 1,
    "pagination": {
      "current": 1,
      "previous": null,
      "next": 2,
      "per_page": 10,
      "pages": 1,
      "count": 1
    }
  }

By default only wallpapers marked as safe are returned. This can be changed by passing a safe_filter parameter. The parameter can have the following values:

• safe: This is the default, only returns safe wallpapers.
• include_pending: Returns safe as well as pending (not yet rated) wallpapers.
• all: Returns all wallpapers, including not safe for work wallpapers.

$ curl https://api.desktoppr.co/1/users/keithpitt/wallpapers?safe_filter=all
  {
    "response": [ {
        "id": 380,
        "bytes": 990121,
        "created_at": "2012-04-11T10:33:27Z",
        "image":{
          "url": "http://...",
          "thumb": {
            "url":"http://..."
          },
          "preview": {
            "url":"http://..."
          },
        },
        "height":1080,
        "width":1920,
        "uploader":"mariovisic",
        "user_count":3,
        "palette":[
          "C4C9CA",
          "7D95A1",
          "282827",
          "32515A",
          "636139"
        ]
    } ],
    "count": 1,
    "pagination": {
      "current": 1,
      "previous": null,
      "next": 2,
      "per_page": 10,
      "pages": 1,
      "count": 1
    }
  }

To get a random wallpaper that a user has in their collection

$ curl https://api.desktoppr.co/1/users/keithpitt/wallpapers/random
  {
    "response": {
      "id": 380,
      "bytes": 990121,
      "created_at": "2012-04-11T10:33:27Z",
      "image":{
        "url": "http://...",
        "thumb": {
          "url":"http://..."
        },
        "preview": {
          "url":"http://..."
        },
      },
      "height":1080,
      "width":1920,
      "uploader":"mariovisic",
      "user_count":3,
      "palette":[
        "C4C9CA",
        "7D95A1",
        "282827",
        "32515A",
        "636139"
      ]
    }
  }

To get a paginated list of wallpapers that a user has liked

$ curl https://api.desktoppr.co/1/users/keithpitt/likes
  {
    "response": [ {
        "id": 380,
        "bytes": 990121,
        "created_at": "2012-04-11T10:33:27Z",
        "image":{
          "url": "http://...",
          "thumb": {
            "url":"http://..."
          },
          "preview": {
            "url":"http://..."
          },
        },
        "height":1080,
        "width":1920,
        "uploader":"mariovisic",
        "user_count":3,
        "palette":[
          "C4C9CA",
          "7D95A1",
          "282827",
          "32515A",
          "636139"
        ]
    } ],
    "count": 1,
    "pagination": {
      "current": 1,
      "previous": null,
      "next": 2,
      "per_page": 10,
      "pages": 1,
      "count": 1
    }
  }

Followers

To get a paginated list of users that a user has followed, or are following, you can use the following endpoints:

$ curl https://api.desktoppr.co/1/users/keithpitt/followers
  {
    "response": [ { ... } ],
    "count": "...",
    "pagination": "..."
  }

$ curl https://api.desktoppr.co/1/users/keithpitt/following
  {
    "response": [ { ... } ],
    "count": "...",
    "pagination": "..."
  }

You can follow a user as follows:

$ curl -u "username:PASSWORD" -X POST \
     http://api.desktoppr.co/1/users/keithpitt/follow
  {
    "response": {
      "ok": true
    }
  }
  

And to unfollow:

$ curl -u "username:PASSWORD" -X DELETE \
     http://api.desktoppr.co/1/users/keithpitt/follow
  {
    "response": {
      "ok": true
    }
  }
  

Wallpapers

To get all wallpapers in the database that have been marked as safe:

$ curl https://api.desktoppr.co/1/wallpapers
  {
    "response": [ {
        "id": 380,
        "bytes": 990121,
        "created_at": "2012-04-11T10:33:27Z",
        "image":{
          "url": "http://...",
          "thumb": {
            "url":"http://..."
          },
          "preview": {
            "url":"http://..."
          },
        },
        "height":1080,
        "width":1920,
        "uploader":"mariovisic",
        "user_count":3,
        "palette":[
          "C4C9CA",
          "7D95A1",
          "282827",
          "32515A",
          "636139"
        ]
    } ],
    "count": 13435,
    "pagination": {
      "current": 1,
      "previous": null,
      "next": 2,
      "per_page": 10,
      "pages": 341,
      "count": 1
    }
  }

You can append a page parameter to cycle through different pages

$ curl https://api.desktoppr.co/1/wallpapers?page=2
  {
    "response": [ {
        "id": 380,
        "bytes": 990121,
        "created_at": "2012-04-11T10:33:27Z",
        "image":{
          "url": "http://...",
          "thumb": {
            "url":"http://..."
          },
          "preview": {
            "url":"http://..."
          },
        },
        "height":1080,
        "width":1920,
        "uploader":"mariovisic",
        "user_count":3,
        "palette":[
          "C4C9CA",
          "7D95A1",
          "282827",
          "32515A",
          "636139"
        ]
    } ],
    "count": 20,
    "pagination": {
      "current": 2,
      "previous": 1,
      "next": 3,
      "per_page": 20,
      "pages": 3558,
      "count": 71142
    }
  }

As with a users wallpaper, you can grab a random SFW wallpaper from our entire database using:

$ curl https://api.desktoppr.co/1/wallpapers/random
  {
    "response": {
      "id": 380,
      "bytes": 990121,
      "created_at": "2012-04-11T10:33:27Z",
      "image":{
        "url": "http://...",
        "thumb": {
          "url":"http://..."
        },
        "preview": {
          "url":"http://..."
        },
      },
      "height":1080,
      "width":1920,
      "uploader":"mariovisic",
      "user_count":3,
      "palette":[
        "C4C9CA",
        "7D95A1",
        "282827",
        "32515A",
        "636139"
      ]
    }
  }

Liking

Liking of wallpapers can be performed via the API. You'll need to be authenticated to like a paticular wallpaper as the current user will be the one liking the wallpaper.

$ curl -u "username:PASSWORD" -X POST http://api.desktoppr.co/1/user/wallpapers/100/like
  {
    "response": {
      "ok": true
    }
  }
  

To unlike a previously liked wallpaper

$ curl -u "username:PASSWORD" -X DELETE http://api.desktoppr.co/1/user/wallpapers/100/like
  {
    "response": {
      "ok": true
    }
  }
  

You can determine if the user has liked a paticular wallpaper, by adding a wallpaper_id query to the call.

$ curl https://api.desktoppr.co/1/users/keithpitt/likes?wallpaper_id=184381
  {
    "response": [ { ... } ],
    "count": "1",
    "pagination": "..."
  }

It will either return a list with 1 wallpaper if they have liked it already, or an empty list if they haven't.

Syncing

Just like liking, syncing can also be performed via the API.

$ curl -u "username:PASSWORD" -X POST \
     http://api.desktoppr.co/1/user/wallpapers/100/selection
  {
    "response": {
      "ok": true
    }
  }
  

To unsync a previously synced wallpaper

$ curl -u "username:PASSWORD" -X DELETE \
     http://api.desktoppr.co/1/user/wallpapers/100/selection
  {
    "response": {
      "ok": true
    }
  }
  

You can determine if the user has synced a paticular wallpaper, by adding a wallpaper_id query to the call.

$ curl https://api.desktoppr.co/1/users/keithpitt/wallpapers?wallpaper_id=256167
  {
    "response": [ { ... } ],
    "count": "1",
    "pagination": "..."
  }

It will either return a list with 1 wallpaper if they have synced it already, or an empty list if they haven't.

Flagging

Users can flag a wallpaper to indicate it is safe for work, not safe for work, or not suitable for the website and should be deleted. Flagging requires you to be logged in.

Flagging a wallpaper as safe for work:

$ curl l -u "username:PASSWORD" -X POST \
    https://api.desktoppr.co/1/wallpapers/30000/flag_safe
  {
    "response": [ { ... } ],
    "count": "...",
    "pagination": "..."
  }

Flagging a wallpaper as not safe for work:

$ curl l -u "username:PASSWORD" -X POST \
    https://api.desktoppr.co/1/wallpapers/30000/flag_not_safe
  {
    "response": [ { ... } ],
    "count": "...",
    "pagination": "..."
  }

Flagging a wallpaper for deletion as it is not appropriate for the site:

$ curl l -u "username:PASSWORD" -X POST \
    https://api.desktoppr.co/1/wallpapers/30000/flag_deletion
  {
    "response": [ { ... } ],
    "count": "...",
    "pagination": "..."
  }

Applications using the API

Some rather nice people have built application or tools that use the desktoppr API. Here they are

• Tate's Chrome Extension for Desktoppr

  This extension displays a different wallpaper each time you open a new tab in Google Chrome.
  Download Source

• Muzei Desktoppr Extension

  An open source extension for the Muzei Live Wallpaper on Android. Periodically sets a random Desktoppr image as the device wallpaper
  Download Source