Gimme Bar API v1

Last build: Thursday; May 24, 2012 10:19 PM

The Basics

Developer Support

We want to help you use the Gimme Bar API to build super-awesome applications. Here are the best ways to get help or make suggestions:

Getting API Access

To get access to our API, you need to register an application. To register, log-in to your Gimme Bar account, go to https://gimmebar.com/apps, and click on Register Your Application

For now we manually approve each application, so it might take a little bit. We'll try to be quick about it, and let you know as soon as it's ready.

Base URL

The base URL for app v1 API endpoints is:

https://gimmebar.com/api/v1

Authorization and Authentication

We use an OAuth v2-style authentication approach for our API, with a modified flow for devices and desktop apps. Applications need to authenticate with our API to obtain an access token. The access token is used in lieu of a username & password to access a user's data via the Gimme Bar API.

Authorization for devices and desktop apps

An example flow for obtaining an access token might go as follows:

  1. A desktop application retrieves a request token by making an HTTP POST request
  2. The desktop application shows a button to the user labelled "Authorize", and instructions to click on it.
  3. The user clicks on the button, and a web browser is opened to the /authorize page on the Gimme Bar web site.
  4. While the user is working in the browser, the application shows a new button "App Approved!" for the user to click when he or she has finished the approval
  5. The user logs-in to the web site, and approves the application for access to his or her data. This marks the request token as "approved" in the Gimme Bar system.
  6. The web site tells the user to return to the application and indicate that it has been approved.
  7. The user clicks the "App Approved!" button in the application.
  8. The application makes another HTTP POST request to the API to exchange the request token for an authorization token.
  9. The application makes a final HTTP POST request to the API to exchange the authorization token for an access token.
  10. The app saves the access token and uses it to authenticate as the user

Broken into HTTP requests, the flow looks like this:

1. Generate a request token

Request

POST /api/v1/auth/token/request HTTP/1.1
Host: gimmebar.com
Origin: app://com.fictivekin.authtester
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; en-us) AppleWebKit/533.6+ (KHTML, like Gecko) Version/4.0 Safari/528.16 Titanium/1.1.0
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Content-Length: 90
Connection: keep-alive
client_id=dad07fa86765457fa45a36sd5f&client_secret=9183ad09f81094f09d8f0a9d8f0&type=app

Response

HTTP/1.1 200 OK
Date: Wed, 29 Jun 2011 19:08:31 GMT
Server: Apache/2.2.14 (Ubuntu)
X-Powered-By: PHP/5.3.5
Content-Length: 73
Content-Type: application/json; charset=utf-8
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
{"request_token":"390a9b193fc51be1a78d13bf69555212","expires":1309375411}

2. Send the user to the following URL to authorize the application

The URL includes the client_id and request token (as token):

https://gimmebar.com/authorize?client_id=dad07fa86765457fa45a36sd5f&token=390a9b193fc51be1a78d13bf69555212&response_type=code

The user is asked to approve or deny the application's access request. If it's approved, the user is told to close the window and return to the application.

3. Exchange the request token for an authorization token when the user returns

Once the user has approved the request, he/she indicates this to the application. The application can then exchange the now-approved request token for an authorization token.

Request

POST /api/v1/auth/token/authorization HTTP/1.1
Host: gimmebar.com
Origin: app://com.fictivekin.authtester
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; en-us) AppleWebKit/533.6+ (KHTML, like Gecko) Version/4.0 Safari/528.16 Titanium/1.1.0
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Content-Length: 92
Connection: keep-alive
client_id=dad07fa86765457fa45a36sd5f&token=390a9b193fc51be1a78d13bf69555212&response_type=code

Response

HTTP/1.1 200 OK
Date: Wed, 29 Jun 2011 19:08:40 GMT
Server: Apache/2.2.14 (Ubuntu)
X-Powered-By: PHP/5.3.5
Content-Length: 64
Content-Type: application/json; charset=utf-8
Keep-Alive: timeout=15, max=99
Connection: Keep-Alive
{"code":"0cac418f23aebcfafff28d305e0789b6","expires":1309375416}

4. Exchange the authorization token for an access token:

Finally, the application exchanges the authorization token for the access token.

Request

POST /api/v1/auth/token/access HTTP/1.1
Host: gimmebar.com
Origin: app://com.fictivekin.authtester
X-Requested-With: XMLHttpRequest
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; en-us) AppleWebKit/533.6+ (KHTML, like Gecko) Version/4.0 Safari/528.16 Titanium/1.1.0
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Content-Length: 67
Connection: keep-alive
code=0cac418f23aebcfafff28d305e0789b6&grant_type=authorization_code

Response

HTTP/1.1 200 OK
Date: Wed, 29 Jun 2011 19:08:40 GMT
Server: Apache/2.2.14 (Ubuntu)
X-Powered-By: PHP/5.3.5
Content-Length: 210
Content-Type: application/json; charset=utf-8
Keep-Alive: timeout=15, max=98
Connection: Keep-Alive
{"access_token":"ba134627a5d5232c9afd836dc77dc111","refresh_token":"ee1f837e151f44bd7ba138ed44585079","token_type":"bearer","expires_in":null,"user_id":"b2d5da738c097590692cdef33ced2689","username":"funkatron"}

5. Use the access token to authenticate with the API and retrieve user data

You can use HTTP Basic or HTTP Digest authentication, using the user's username as the HTTP username, and the access token as the HTTP password.

Request

GET /api/v1/tags HTTP/1.1
Host: gimmebar.com
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; en-us) AppleWebKit/533.6+ (KHTML, like Gecko) Version/4.0 Safari/528.16 Titanium/1.1.0
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Authorization: Digest username="funkatron", realm="GimmeBarAPI", nonce="7a3ab1f9cde605f27797cd04c4d1fcf6", uri="/api/v1/tags", response="3654f9b1b2ba9489e1f01ae792852987", opaque="94619f8a70068b2591c2eed622525b0e", algorithm="MD5", cnonce="6897ccbff3b08776ab61e69a814c05b4", nc=00000001, qop="auth"
Connection: keep-alive

Note that we use HTTP Digest auth above, but we can also use HTTP Basic auth:

Authorization: Basic ZnVua2F0cm9uOmJhMTM0NjI3YTVkNTIzMmM5YWZkODM2ZGM3N2RjMTEx

or Bearer token auth:

Authorization: Bearer ba134627a5d5232c9afd836dc77dc111

Response

HTTP/1.1 200 OK
Date: Wed, 29 Jun 2011 19:08:40 GMT
Server: Apache/2.2.14 (Ubuntu)
X-Powered-By: PHP/5.3.5
Content-Type: application/json; charset=utf-8
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
["basketball","photography","sf","football"]

Authorization for web sites

A more traditional OAuth v2 approach, using a callback URI identified by redirect_uri. Instead of asking the user to navigate back to the application, the Gimme Bar web site redirect the user's browser to a callback URL, passing the authorization token in the query string.

A couple notes:

More coming soon

Authenticating

Other than the /auth token and /public endpoints, all API methods require authentication. All user authentication is done with an access token, but we support:

Rate limits

Right now we don't have rate limiting. We probably will in the near future. Please don't abuse it. We reserve the right to limit or withdraw access of clients that impact the overall performance of the service.

Requests and Responses

Response formats

The only response format we officially support is JSON. If the API endpoint doesn't include a format suffix, JSON is returned. XML can be returned if the suffix is .xml. JSONP responses can be created by adding a jsonp_callback=function_name parameter to JSON requests.

Formats by suffix

URL Format Content-Type
https://gimmebar.com/api/v1/public/assets/funkatron JSON application/json
https://gimmebar.com/api/v1/public/assets/funkatron.json JSON application/json
https://gimmebar.com/api/v1/public/assets/funkatron.xml XML application/xml
https://gimmebar.com/api/v1/public/assets/funkatron?jsonp_callback=function_name JavaScript application/json

Note: the Content-Type currently returned by JSONP responses is application/json. This may change to a proper JavaScript Content-Type in the future.

JSONP Example

Request

https://gimmebar.com/api/v1/public/assets/funkatron?jsonp_callback=foo&limit=5&_include=title

Response

foo({
    "records":
    [
        {
            "id":"4fa91f86aac422937200000e",
            "title":"(1) Tumblr"
        },
        {
            "id":"4fa91ed929ca15036a00000d",
            "title":"Tempest (1980 Atari) [Re-Uploaded] - YouTube"
        },
        {
            "id":"4fa91bd229ca156769000010",
            "title":"Gmelius\u2122 \u00b7 Ad Remover and Better UI for Gmail\u2122"
        },
        {
            "id":"4fa91bd029ca15626900000b",
            "title":"Chrome Web Store - Minimalist for Everything [Beta]"
        },
        {
            "id":"4fa9170f29ca155b68000008",
            "title":"Chicago Train Congestion Slows Whole Country - NYTimes.com"
        }
    ],
    "skip":0,
    "limit":5,
    "total_records":8763,
    "more_records":true
});

Data formats

Type Notes
STRING Empty strings are considered input (not discarded)
INTEGER
BOOLEAN Boolean input params should be passed as '1' for TRUE and '0' for false
ARRAY Array input params should be passed using the key[]=value&key[]=value&... notation

Paginated response format

Most of the endpoints that return multiple records use a common paginated response structure. These endpoints accept the limit and skip parameters, and will return a response structure with the following properties:

Example

Request

https://gimmebar.com/api/v1/public/assets/funkatron.json?limit=5&_include=title

Response

{
    "records":
    [
        {
            "id":"4fa91f86aac422937200000e",
            "title":"(1) Tumblr"
        },
        {
            "id":"4fa91ed929ca15036a00000d",
            "title":"Tempest (1980 Atari) [Re-Uploaded] - YouTube"
        },
        {
            "id":"4fa91bd229ca156769000010",
            "title":"Gmelius\u2122 \u00b7 Ad Remover and Better UI for Gmail\u2122"
        },
        {
            "id":"4fa91bd029ca15626900000b",
            "title":"Chrome Web Store - Minimalist for Everything [Beta]"
        },
        {
            "id":"4fa9170f29ca155b68000008",
            "title":"Chicago Train Congestion Slows Whole Country - NYTimes.com"
        }
    ],
    "skip":0,
    "limit":5,
    "total_records":8763,
    "more_records":true
}

Entity Includes and Extensions

Includes and Extensions allow you to get more – or less – data in a single API call.

Extensions

Entity extensions allow you to load additional data without making extra API calls. Extensions are defined for User, Collection and Asset entities. Multiple extensions can be applied in a single request.

User Extensions

Collection Extensions

Asset Extensions

Includes

On methods that support it, the _include parameter allows you to pass an array of field names. Only those specified field names will be returned in the result records. The record id is always included. Note that _include only works on root-level properties of records.

Single-entity request

GET https://gimmebar.com/api/v1/public/asset/4f8cd329aac4226e0c000008?_include[]=title&_include[]=short_url_token

Response

{
    "id":"4f8cd329aac4226e0c000008",
    "title":"Blade Runner People\u00a0On-Set",
    "short_url_token":"Cn3t"
}

Paginated request

https://gimmebar.com/api/v1/public/assets/funkatron?limit=3&_include[]=title&_include[]=short_url_token

Response

{
    "records":
    [
        {
            "id":"4fa91f86aac422937200000e",
            "title":"(1) Tumblr",
            "short_url_token":"Gcbb"
        },
        {
            "id":"4fa91ed929ca15036a00000d",
            "title":"Tempest (1980 Atari) [Re-Uploaded] - YouTube",
            "short_url_token":"Gc.T"
        },
        {
            "id":"4fa91bd229ca156769000010",
            "title":"Gmelius\u2122 \u00b7 Ad Remover and Better UI for Gmail\u2122",
            "short_url_token":"Gb8c"
        }
    ],
    "skip":0,
    "limit":3,
    "total_records":8763,
    "more_records":true
}

Error responses

URL parameters

Some methods have a parameter as part of their URL path. These are indicated by a preceding colon. For example:

/user/:user_id

Here the user_id must be passed as part of the path, and cannot be passed in the query string or POST/DELETE parameters.

Methods

Public

GET public/assets/:username

Retrieve public assets for the given username

Authenticated: False
Extensions: ASSET
Paginated: True

URL parameters

key type optional default description
username STRING False None A valid username

Parameters

key type optional default description
type STRING True None
tag STRING True None

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No user with that username

GET public/assets/:username/:collection_slug

Retrieve public assets for the given username

Authenticated: False
Extensions: ASSET
Paginated: True

URL parameters

key type optional default description
username STRING False None A valid username
collection_slug STRING False None A valid collection slug

Parameters

key type optional default description
tag STRING True None

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No user with that username
RESOURCE_NOT_FOUND 404 No collection with that slug

GET public/asset/:asset_id

Retrieve a public asset

Authenticated: False
Extensions: ASSET
Paginated: False

URL parameters

key type optional default description
asset_id STRING False None A valid asset ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No asset with that ID
NOT_AUTHORIZED 403 Asset is private

Authentication

POST auth/token/:token_type

Generate a request, authorization, or authentication token

Authenticated: True
Extensions: None
Paginated: False

URL parameters

key type optional default description
token_type STRING False None The type of token to generate. Must be one of the following: request, authorization, access

Parameters

key type optional default description
type STRING True None Required to generate a request token. Only valid value is 'app'
client_id STRING True None The API client's ID. Required to generate a request token or authorization token
client_secret STRING True None The API client's secret. Required to generate a request token
response_type STRING True None Required to generate a authorization token. Only valid value is 'code'
client_id STRING True None The API client's ID. Required to generate a authorization token
token STRING True None A valid, non-expired, user-approved request token. Required to generate a authorization token
grant_type STRING True None Required to generate an access token. Only valid value is 'authorization_code'
code STRING True None A valid, non-expired request token. Required to generate an access token

Errors

type HTTP Code reason
INVALID_INPUT 400 Invalid token type
INVALID_INPUT 400 type must be "app"
INVALID_INPUT 400 response_type must be "code"
INVALID_INPUT 400 grant_type must be "authorization_code"
INVALID_INPUT 400 Invalid client_id
INVALID_INPUT 400 Client is not approved for access
API_ERROR 500 Error creating request token
API_ERROR 500 Error creating authorization token
API_ERROR 500 Error creating access token
API_ERROR 500 Other token generation error

GET auth/test

Test authentication. If successful, returns { "success" : true }

Authenticated: True
Extensions: None
Paginated: False

Users

GET users

Get users, or matching usernames. One (and only one) of the following parameters is required: 'username', match', 'friends', 'stellar'.

Note that the full set of results are always returned; limit/skip params are ignored

Authenticated: True
Extensions: USER
Paginated: True

Parameters

key type optional default description
username STRING True None A valid username. If set, method will return a single user record that matches the username
match STRING True None A string prefix to match against existing usernames. A maximum of 5 matches will be returned, as an array of username/id results. If no results, returns an empty array.
stellar BOOLEAN True None Return the full set of 'stellar' users
friends BOOLEAN True None Return the full set of the authenticating user's "friends". If the authenticating user follows another user's public firehose collection, they are considered a friend of the authenticating user.

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 Username not found
INVALID_INPUT 400 Must pass 'username', match', 'friends' or 'stellar' parameter

GET users/avatar

Retrieve the avatar URL for the given username

Authenticated: True
Extensions: None
Paginated: False

Parameters

key type optional default description
username STRING False None A valid username

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 User not found
RESOURCE_NOT_FOUND 404 Avatar asset not found

GET user/:user_id

Get a given user by user_id

Authenticated: True
Extensions: USER
Paginated: False

URL parameters

key type optional default description
user_id STRING False None A valid user ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 User not found

GET user/:user_id/avatar

Retrieve the avatar URL for the given user

Authenticated: True
Extensions: None
Paginated: False

URL parameters

key type optional default description
user_id STRING False None A valid user ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 User not found
RESOURCE_NOT_FOUND 404 Avatar asset not found

Assets

POST asset

Create a new asset. The API will determine the type of asset based on examination of the data passed. To create an asset, one (and only one) of the following must be passed: url, text, data, dataurl

Authenticated: True
Extensions: ASSET
Paginated: False

Parameters

key type optional default description
title STRING False None A title for the asset
source STRING False None Where the asset comes from. In most cases this should be a URL.
url STRING True None Create an asset from a URL
text STRING True None Create an asset from text
data FILE True None HTML form-encoded binary data. File cannot be over 5MB
dataurl STRING True None Base64-encoded binary data
description STRING True None The asset's description. Tags are also applied using this parameter, in #hashtag format
private BOOLEAN True False The asset's private state
use_prev BOOLEAN True False If true, the API will search the user's existing assets with the same source. If one is found, the new asset will inherit the previous asset's title, description, tags, and collections
from_backup BOOLEAN True False Whether this asset should be considered a "backup" from an external service
prevent_capture BOOLEAN True False If this is a page asset, setting this to true will prevent a screenshot from being captured
collection_id ARRAY True None The IDs of one or more collections. The created asset will be added to the designated collections

Errors

type HTTP Code reason
FILE_UPLOAD_FAILED 400 File size was 0
FILE_UPLOAD_FAILED 500 Processing of uploaded file failed
INVALID_INPUT 400 Malformed data URL
INVALID_INPUT 400 Must provide one of the following parameters: url, text, data, dataurl
API_ERROR 500 Error creating asset
API_ERROR 500 Error adding extservice_data
API_ERROR 500 Error adding to collection

GET asset/:asset_id

Get an existing asset

Authenticated: True
Extensions: ASSET
Paginated: False

URL parameters

key type optional default description
asset_id STRING False None A valid asset ID

Parameters

key type optional default description
collection_id STRING True None A collection id to use as context for viewing the asset
repeat BOOLEAN True False If true, the dupes property can contain multiple assets from the same owner

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 Asset not found
NOT_AUTHORIZED 403 The authenticating user does not have permission to views this asset

POST asset/:asset_id

Alter an existing asset

Authenticated: True
Extensions: ASSET
Paginated: False

URL parameters

key type optional default description
asset_id STRING False None A valid asset ID

Parameters

key type optional default description
title STRING True None Set the asset's title
description BOOLEAN True None Set the asset's description. Tags are also applied using this parameter, in #hashtag format
private BOOLEAN True None Set the asset's private state
collection_id STRING True None A collection id to use as context for viewing the asset when returned. NOT USED TO SET COLLECTIONS TO WHICH THE ASSET BELONGS.

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 Asset not found
NOT_AUTHORIZED 403 The authenticating user does not own this asset

DELETE asset/:asset_id

Delete a given asset

Authenticated: True
Extensions: None
Paginated: False

URL parameters

key type optional default description
asset_id STRING False None A valid asset ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 Asset not found
NOT_AUTHORIZED 403 The authenticating user does not own this asset

POST asset/:asset_id/copy

Make a copy of another user's asset

Authenticated: True
Extensions: ASSET
Paginated: False

URL parameters

key type optional default description
asset_id STRING False None A valid asset ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 Asset not found
INVALID_INPUT 400 You cannot copy your own asset
INVALID_INPUT 400 You cannot copy an asset you already own (by media hash)
API_ERROR 500 Problem copying asset

GET assets

Enter a description here

Authenticated: True
Extensions: ASSET
Paginated: True

Parameters

key type optional default description
user_id STRING True None If passed, limit results to assets owned by the given user. Otherwise, return assets for the authenticating user
type STRING True None If passed, limit results to assets of the given type. Type may be one of the following: image, embed, audio, document, page, text, recipe, article, status
tag ARRAY True None If passed, limit results to assets that match all passed tags
private BOOLEAN True None If passed, limit results based on private state
asset_id ARRAY True None An array of asset IDs. Retrieves only the indicated assets. Other parameters ignored
watched BOOLEAN True None If true, retrieve assets from collections the autheticating user is watching. Other parameters ignored. This is used to generate the Discovery stream on the Gimme Bar web site
hash STRING True None If passed, retrieve all assets with the same media hash. Other parameters ignored
include_backups ARRAY True all used to include/filter backups assets. Possible values: 'none', 'all', 'delicious', 'pinboard', 'twitter', 'twitter_fav', 'instagram', 'instagram_fav'

GET assets/search

Enter a description here

Authenticated: True
Extensions: ASSET
Paginated: True

Parameters

key type optional default description
terms STRING False None Terms to search for
user_id STRING True None A valid user_id. If provided, the search is performed on that user's assets. If not, the authenticated user's assets are searched
type STRING False None A valid asset type. If provided, results are limited to the given type

Errors

type HTTP Code reason
SEARCH_ERROR 500 There was a problem running your search

GET assets/totals

Returns a breakdown of asset counts by type for the authenticated user

Authenticated: True
Extensions: None
Paginated: False

Parameters

key type optional default description
user_id STRING False None A valid user ID
include_private BOOLEAN True False If true, include private assets in counts. Ignored if user_id is not the authenticated user

Collections

POST collection

Creates a new desciption owned by the authenticated user

Authenticated: True
Extensions: COLLECTION
Paginated: False

Parameters

key type optional default description
title STRING False None The title for the new collection
description STRING True None A description for the new collection
private BOOLEAN True False Whether or not the collection will be private. Default is false

Errors

type HTTP Code reason
INVALID_INPUT 400 User already has a collection with this name
API_ERROR 500 Problem adding collection

GET collection/:collection_id

Retrieve an existing collection by ID

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID
NOT_AUTHORIZED 403 User does not have permission to read this collection

POST collection/:collection_id

Modify an existing collection. Pass only parameters you want to change

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Parameters

key type optional default description
title STRING True None The new title for the collection. Changing this also changes the collection URL slug
description STRING True None The new description for the collection
private STRING True None The new private state for the collection

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID
NOT_AUTHORIZED 403 User does not have permission to read this collection
API_ERROR 500 Error updating collection

DELETE collection/:collection_id

Delete an existing collection

Authenticated: True
Extensions: None
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID
NOT_AUTHORIZED 403 Not authorized to delete that collection

GET collection/:collection_id/assets

Get assets in a given collection

Authenticated: True
Extensions: ASSET
Paginated: True

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Parameters

key type optional default description
type STRING True None A valid asset type. If passed, only return assets of this type

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID
NOT_AUTHORIZED 404 User not authorized to view this collection

POST collection/:collection_id/assets

Add assets to a collection

Authenticated: True
Extensions: ASSET
Paginated: True

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Parameters

key type optional default description
asset_id ARRAY False None A set of valid asset IDs. If passed, only return assets of this type

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID
NOT_AUTHORIZED 403 User not authorized to add assets to this collection
RESOURCE_NOT_FOUND 404 No asset with ID
NOT_AUTHORIZED 403 User does not own asset
NOT_AUTHORIZED 403 Cannot add private asset
API_ERROR 500 Error adding asset to collection

DELETE collection/:collection_id/assets

Delete assets from a collection

Authenticated: True
Extensions: ASSET
Paginated: True

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Parameters

key type optional default description
asset_id ARRAY False None A set of valid asset IDs. If passed, only return assets of this type

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID
RESOURCE_NOT_FOUND 404 No asset with ID
NOT_AUTHORIZED 403 User does not own asset
API_ERROR 500 Error adding asset to collection

POST collection/:collection_id/invitation

Create an invitiation to collaborate on a collection with another user

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Parameters

key type optional default description
user_id STRING False None The user to invite to collaborate
access_level STRING False None The level of access to give the invited user. Must be 'owner' or 'member'

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID

DELETE collection/:collection_id/invitation

NOT YET IMPLEMENTED

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID

POST collection/:collection_id/invitation/mine

Accept an invitation to collaborate on a collection

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID

DELETE collection/:collection_id/invitation/mine

Decline an invitation to collaborate on a collection

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID

POST collection/:collection_id/user/:user_id

Change a user's access level to a collaborative collection

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID
user_id STRING False None A valid user ID

Parameters

key type optional default description
access STRING False None The level of access to give the user. Must be 'owner' or 'member'

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID

DELETE collection/:collection_id/user/:user_id

Remove a user's access to a collaborative collection

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID
user_id STRING False None A valid user ID

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 No collection with that ID

POST collection/:collection_id/watch

Start watching a collection (so it shows up in your discovery stream)

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Errors

type HTTP Code reason
API_ERROR 500 Error watching collection

DELETE collection/:collection_id/watch

Stop watching a collection (so it no longer shows up in your discovery stream)

Authenticated: True
Extensions: COLLECTION
Paginated: False

URL parameters

key type optional default description
collection_id STRING False None A valid collection ID

Errors

type HTTP Code reason
API_ERROR 500 Error watching collection

GET collections

Return multiple collections, or a collection by slug

Authenticated: True
Extensions: COLLECTION
Paginated: True

Parameters

key type optional default description
watched BOOLEAN True None If passed and true, collectiosn being watched by the authenticated user are returned, and other parameters are ignored
slug STRING True None A valid collection slug. If passed, the collection with the matching slug, owned by the authenticated user, is returned. Other parameters ignored
asset_id ARRAY True None A set of asset IDs. If passed, collections that contain one or more of the assets are returned. Other parameters are ignored
user_id STRING True AUTH_ID A valid user ID. If not passed, the authenticated user's ID is used
private BOOLEAN True None Whether to return only private collections, or only public collections. If not passed, both are retuned.

If a user_id was passed and it's not the authenticated user's ID, only public collections are returned

Errors

type HTTP Code reason
RESOURCE_NOT_FOUND 404 Collection not found with passed slug
RESOURCE_NOT_FOUND 404 No collections found

GET collections/notable

Get 'notable' collections. This set is curated by the Gimme Bar team

Authenticated: True
Extensions: COLLECTION
Paginated: True

GET collections/recommended

Get 'recommended' collections. These are currently collections created by people you follow on Twitter (if you've associated your account with a Twitter account)

Authenticated: True
Extensions: COLLECTION
Paginated: True