Gimme Bar Public API

Last update: 14 Nov 2011 14:44:37 -0400

Welcome to the Gimme Bar API docs!

Right now our API is very much in flux, so while on v0, expect changes. We’ll do our best to let you know about them ahead of time.

As we grow, we’ll add more resources: example libraries, discussion groups, and the like.

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:

  1. IRC: We hang out in #gimmebar-dev on the Freenode network
  2. E-mail: Contact us at api@gimmebar.com

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

https://gimmebar.com/api/v0

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 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 user is told 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/v0/auth/reqtoken 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

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

Request

POST /api/v0/auth/exchange/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: 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:

Request

POST /api/v0/auth/exchange/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: 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

Request

GET /api/v0/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/v0/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
[{"tag":"basketball","count":6},{"tag":"photography","count":1},{"tag":"sf","count":3},{"tag":"football","count":40}]

Authorization for web sites

A more traditional OAuth v2 approach, using a callback URI. More info 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.

Response formats

Data formats

Error responses

{
	"errors":
	[
		{
			"message":"Missing required parameters",
			"name":"ERROR_MISSING_REQUEST_ARG",
			"at":"Required Parameters: asset_id"
		}
	]
}

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

Get all public assets for the passed username. Assets are returned sorted by add date, descending (most recent first).

Parameters
Key Type Required Note
username String True URL path parameter
type String False See below for valid types
tag String / Array False
limit Integer False Default is 10, Max 50
skip Integer False Default is 0 (first asset)
Example
Request
curl "https://gimmebar.com/api/v0/public/assets/funkatron"

JSON Response

Note: For brevity we are not listing all the assets returned here

{
	"more_records":true,
	"records":
	[
		{
			"id":"4e131e71827a9f5c05000000",
			"asset_type":"embed",
			"content":
			{
				"tag":"OBJECT",
				"attributes":
				{
					"height":"100%",
					"width":"100%",
					"src":"http:\/\/a.vimeocdn.com\/p\/flash\/moogaloop\/5.1.18\/moogaloop.swf?v=1.0.0",
					"type":"application\/x-shockwave-flash",
					"flashvars":"server=vimeo.com&player_server=player.vimeo.com&cdn_server=a.vimeocdn.com&embed_location=http%3A%2F%2Fvimeo.com%2Fchannels%2Fstaffpicks&force_embed=0&force_info=1&moogaloop_type=moogaloop_local&js_api=1&js_getConfig=player24504225_1357343952.getConfig&js_setConfig=player24504225_1357343952.setConfig&clip_id=24504225&fullscreen=1&js_onLoad=player24504225_1357343952.player.moogaloopLoaded&js_onThumbLoaded=player24504225_1357343952.player.moogaloopThumbLoaded"
				}
			},
			"date":1309875825,
			"media_hash":"2cd5d03dc898f0bb93c6da7912694e85528",
			"mime_type":"text\/-gimmebar-embed",
			"private":false,
			"size":653,
			"source":"http:\/\/vimeo.com\/channels\/staffpicks#24504225",
			"description":"",
			"tags":
			[
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"Vimeo Staff Picks on Vimeo",
			"short_url":"http:\/\/example.gimm.ie\/aFP"
		},
		/* more asset objects */
	],
	"total_records":1833,
	"limit":10,
	"skip":0
}

GET /public/assets/:username/:collection

Get all public assets from a user’s collection. Assets are returned sorted by add date, descending (most recent first).

Parameters
Key Type Required Note
username String True URL path parameter
collection String True The collection slug. URL path parameter
type String False See below for valid types
limit Integer False Default is 10, Max 50
skip Integer False Default is 0 (first asset)
Example
Request
curl "https://gimmebar.com/api/v0/public/assets/funkatron/bonus-score-2"

JSON Response

Note: For brevity we are not listing all the assets returned here

{
	"records":
	[
		{
			"id":"4d9f501b827a9fbf040000a5",
			"asset_type":"image",
			"content":
			{
				"full":"http:\/\/gimmebar.com:8001\/4d9f501b7fe5d.jpg",
				"original":"http:\/\/www.blogcdn.com\/www.engadget.com\/media\/2011\/04\/rav4-2011-04-08-600.jpg"
			},
			"date":1302286363,
			"media_hash":"26e184347b47a32c8f31abe3920d978553569",
			"mime_type":"image\/jpeg",
			"private":false,
			"size":53569,
			"source":"http:\/\/www.engadget.com\/",
			"description":"",
			"tags":
			[
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"Engadget\u2019s tesla picture is cool\u00a7",
			"short_url":"http:\/\/gim.ie\/aqm"
		},
		/* more asset objects */
	],
	"more_rows":false,
	"total_rows":9,
	"skip":0,
	"limit":10
}

Auth

POST /auth/reqtoken

Generate a request token. This is the first step in the desktop/device authorization flow.

Parameters
Key Type Required Note
client_id ID True
client_secret string True
type string True only ‘app’ is supported currently
Example
Request
curl -vi https://gimmebar.com/api/v0/auth/reqtoken \
	-d "client_id=CLIENT_ID" \
	-d "client_secret=CLIENT_SECRET" \
	-d "type=app"

JSON Response
{
	"request_token":"b1521214de316ec0e8c2f703c5ad435c",
	"expires":1310097543
}

POST /auth/exchange/request

Exchange an approved request token for an authorization token.

Parameters
Key Type Required Note
client_id ID True
client_secret string True
response_type string True only ‘code’ is supported currently
Example
Request
curl -vi https://gimmebar.com/api/v0/auth/exchange/request \
	-d "client_id=CLIENT_ID" \
	-d "client_secret=CLIENT_SECRET" \
	-d "response_type=code"

JSON Response
{
	"code":"0cac418f23aebcfafff28d305e0789b6",
	"expires":1309375416
}

POST /auth/exchange/authorization

Exchange an authorization token for an access token.

Parameters
Key Type Required Note
code string True the authorization token (or ‘code’)
grant_type string True only ‘authorization_code’ is supported currently
Example
Request
curl -vi https://gimmebar.com/api/v0/auth/exchange/authorization \
	-d "code=AUTHORIZATION_TOKEN" \
	-d "grant_type=authorization_code"

JSON Response
{
	"access_token":"ba134627a5d5232c9afd836dc77dc111",
	"refresh_token":"ee1f837e151f44bd7ba138ed44585079",
	"token_type":"bearer",
	"expires_in":null,
	"user_id":"b2d5da738c097590692cdef33ced2689",
	"username":"funkatron"
}

GET /auth/test

Method for testing user API authentication. Will return 401 status on failure.

Example
Request

With a valid access key, all of the following authentication methods will work:

curl -u USERNAME:ACCESSKEY https://gimmebar.com/api/v0/auth/test

curl --digest -u USERNAME:ACCESSKEY https://gimmebar.com/api/v0/auth/test

curl -H "Authorization: Bearer ACCESSKEY" https://gimmebar.com/api/v0/auth/test

Response
{"success":true}

User

GET /user

Returns the profile of the authenticating user.

Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/user"

JSON Response
{
	"id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"username":"funkatron",
	"signup_date":1288357804,
	"avatar_image_url":"http://s3.amazonaws.com/resized-images/7b32f906-176c-4113-89bb-a4bd66b0cb97"
}

GET /user/:user_id

Returns the profile corresponding to the given user_id.

Parameters
Key Type Required Note
user_id ID True URL path parameter
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/user/0529f5c0ab9fbddc90dd7d1f1e101d74"

JSON Response
{
	"id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"username":"funkatron",
	"signup_date":1288357804,
	"avatar_image_url":"http://s3.amazonaws.com/resized-images/7b32f906-176c-4113-89bb-a4bd66b0cb97"
}

GET /users/find

Find a user by username.

Parameters
Key Type Required Note
username String True
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/users/find?username=funkatron"

JSON Response
{
	"id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"username":"funkatron",
	"signup_date":1288357804,
	"avatar_image_url":"http://s3.amazonaws.com/resized-images/7b32f906-176c-4113-89bb-a4bd66b0cb97"
}

Assets

Some methods in the Assets section allow you to specify an asset type. The type value must be one of the following:

The property that contains the content of an asset varies by type. Here’s a breakdown:

image
embed

Embeds vary greatly based on the data we get back from the service. Generally we try to include the embed tag data, as well as any flash vars stored with it.

The content property from a typical YouTube embed capture will look like this:

{
	"url":null,
	"type":"embed",
	"thumbnail":"http:\/\/i3.ytimg.com\/vi\/rlmRjqBt_mE\/hqdefault.jpg",
	"title":"Louis Armstrong and Frank Sinatra Sing Death Metal",
	"info":
	{
		"provider_url":"http:\/\/www.youtube.com\/",
		"title":"Louis Armstrong and Frank Sinatra Sing Death Metal",
		"html":"<object width=\"425\" height=\"344\"><param name=\"movie\" value=\"http:\/\/www.youtube.com\/v\/rlmRjqBt_mE?version=3\"><\/param><param name=\"allowFullScreen\" value=\"true\"><\/param><param name=\"allowscriptaccess\" value=\"always\"><\/param><embed src=\"http:\/\/www.youtube.com\/v\/rlmRjqBt_mE?version=3\" type=\"application\/x-shockwave-flash\" width=\"425\" height=\"344\" allowscriptaccess=\"always\" allowfullscreen=\"true\"><\/embed><\/object>",
		"author_name":"AndyRehfeldt",
		"height":344,
		"thumbnail_width":480,
		"width":425,
		"version":"1.0",
		"author_url":"http:\/\/www.youtube.com\/user\/AndyRehfeldt",
		"provider_name":"YouTube",
		"thumbnail_url":"http:\/\/i3.ytimg.com\/vi\/rlmRjqBt_mE\/hqdefault.jpg",
		"type":"video",
		"thumbnail_height":360
	},
	"assimilator_type":"Oembed",
	"assimilator_subtype":"YouTube",
	"params":
	{
		"tag":"embed",
		"src":"http:\/\/www.youtube.com\/v\/rlmRjqBt_mE?version=3",
		"width":"425",
		"height":"344"
	}
},

A typical Vimeo content property will look like this:

{
	  "tag":"OBJECT",
	  "attributes":
	  {
		  "height":"100%",
		  "width":"100%",
		  "src":"http:\/\/a.vimeocdn.com\/p\/flash\/moogaloop\/5.1.18\/moogaloop.swf?v=1.0.0",
		  "type":"application\/x-shockwave-flash",
		  "flashvars":"server=vimeo.com&player_server=player.vimeo.com&cdn_server=a.vimeocdn.com&embed_location=http%3A%2F%2Fvimeo.com%2Fchannels%2Fstaffpicks&  force_embed=0&force_info=1&moogaloop_type=moogaloop_local&js_api=1&js_getConfig=player24504225_1357343952.getConfig&  js_setConfig=player24504225_1357343952.setConfig&clip_id=24504225&fullscreen=1&js_onLoad=player24504225_1357343952.player.moogaloopLoaded&  js_onThumbLoaded=player24504225_1357343952.player.moogaloopThumbLoaded"
	  }
},

page
text

Other content types will be supported in the near future.

POST /asset

Create a new asset

Parameters
Key Type Required Note
title String True
source String True
description String / Array False tags are generated from this parameter
collection_id ID / Array False
private Boolean False

In addition, one of the following parameters must be passed. The type of asset created is determined by which parameter is supplied

Key Type Required Note
url URL String False page or image from URL
text String False Creates a text asset
embed Embed Object False Creates an embed
oembed Oembed Object False Creates an embed
data File False Upload a file. image or document
Example
Request
curl -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/asset" \
	--data-urlencode "title=test title" \
	--data-urlencode "source=upload" \
	--data-urlencode "description=This is the description of my asset #foo #bar #baz" \
	--data-urlencode "collection_id[]=4d6d6cf9827a9f7c1000002e" \
	--data-urlencode "collection_id[]=4d6d5212827a9f2c56000002" \
	--data-urlencode "private=false" \
	--data-urlencode "url=http://teuxdeux.com/"

JSON Response
{
	"id": "4e10b31e827a9f8d04000000",
	"asset_type": "page",
	"content": {
		"full": "http://gimmebar.example.com/4e10b31d46d54.html",
		"original": "http://teuxdeux.com/",
		"fullscreen": "http://s3.amazonaws.com/gimme-grabs-new/E1023932-95B5-4538-AC5E-2C626C444D5B",
		"thumb": "http://s3.amazonaws.com/gimme-grabs-new/3500977B-D62C-43CE-A3F6-2F319A942C35"
	},
	"date": 1309717278,
	"media_hash": "49a2db07eba30646832d510264b457cd21397",
	"mime_type": "text/html",
	"private": false,
	"size": 21397,
	"source": "upload",
	"description": "This is the description of my asset #foo #bar #baz",
	"tags": [
		"foo",
		"bar",
		"baz"
	],
	"username": "funkatron",
	"user_id": "0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title": "test title",
	"short_url": "http://example.gim.ie/aFE"
}

Request
curl -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/asset" \
	-F "title=His Holiness" \
	-F "source=upload" \
	-F "description=#quotes" \
	-F "collection_id[]=4d6d6cf9827a9f7c1000002e" \
	-F "private=false" \
	-F data=@./hh.txt

JSON Response
{
	"id":"4e10b325827a9f8a0400000d",
	"asset_type":"page",
	"content":
	{
		"full":"http://gimmebar.example.com/4dac95dfa9435.plain"
	},
	"date":1309717285,
	"media_hash":"005eb815e3bdb75f87b7d7e0f04a10022918",
	"mime_type":"text/plain",
	"private":false,
	"size":2918,
	"source":"upload",
	"description":"#quotes",
	"tags":
	[
		"quotes"
	],
	"username":"funkatron",
	"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title":"His Holiness",
	"short_url":"http://example.gim.ie/aFL"
}

Request
curl -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/asset" \
	-F "title=Clever Girl" \
	-F "source=upload" \
	-F "description=#animals I love this pic" \
	-F "private=true" \
	-F data=@./67TD9.jpg

JSON Response
{
	"id":"4e10b325827a9fbe04000004",
	"asset_type":"image",
	"content":
	{
		"full":"http://gimmebar.example.com/4e10b31e63433.jpg",
		"display":"http://s3.amazonaws.com/resized-images-new/B00B240F-2005-41B5-A0EF-6AC8823D04D2",
		"stash":"http://s3.amazonaws.com/resized-images-new/9375D3DD-EE48-439F-8367-6F973B490D0C"
	},
	"date":1309717285,
	"media_hash":"f76fc3cd3a5c4415628ed9ae87e7e5d1126927",
	"mime_type":"image/jpeg",
	"private":true,
	"size":126927,
	"source":"upload",
	"description":"#animals I love this pic",
	"tags":
	[
		"animals"
	],
	"username":"funkatron",
	"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title":"Clever Girl",
	"short_url":"http://example.gim.ie/aFM"
}

GET /asset/:asset_id

Get the asset with the given asset_id. If the asset is not owned by the authenticating user and is private, a 404 Not Found status is returned.

Parameters
Key Type Required Note
asset_id ID / Array True URL path parameter
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/asset/4e10b31e827a9f8d04000000"

JSON Response
{
	"id": "4e10b31e827a9f8d04000000",
	"asset_type": "page",
	"content": {
		"full": "http://gimmebar.example.com/4e10b31d46d54.html",
		"original": "http://teuxdeux.com/",
		"fullscreen": "http://s3.amazonaws.com/gimme-grabs-new/E1023932-95B5-4538-AC5E-2C626C444D5B",
		"thumb": "http://s3.amazonaws.com/gimme-grabs-new/3500977B-D62C-43CE-A3F6-2F319A942C35"
	},
	"date": 1309717278,
	"media_hash": "49a2db07eba30646832d510264b457cd21397",
	"mime_type": "text/html",
	"private": false,
	"size": 21397,
	"source": "upload",
	"description": "This is the description of my asset #foo #bar #baz",
	"tags": [
		"foo",
		"bar",
		"baz"
	],
	"username": "funkatron",
	"user_id": "0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title": "test title",
	"short_url": "http://example.gim.ie/aFE"
}

POST /asset/:asset_id

Update/change an asset

Parameters
Key Type Required Note
asset_id ID / Array True URL path parameter
title String False
tag String / Array False
private Boolean False
Example
Request
curl -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/asset/4d74f3bd827a9ff106000003" \
	--data-urlencode "title=Change this title"

JSON Response
{
	"id":"4d74f3bd827a9ff106000003",
	"asset_type":"page",
	"content":
	{
		"full":"http://gimmebar.example.com/4d74f3bc24c0b.html",
		"original":"http://www.engadget.com/2011/03/07/lenovo-posts-thinkpad-x220-specs-online-includes-ips-display-s/"
	},
	"date":1299510205,
	"media_hash":"24ffbde453065ee2a1c9f0212af1e9a9107",
	"mime_type":"text/html",
	"private":false,
	"size":65356,
	"source":"http://www.engadget.com/2011/03/07/lenovo-posts-thinkpad-x220-specs-online-includes-ips-display-s/",
	"description":"#fooooooooo",
	"tags":
	[
		"fooooooooo"
	],
	"username":"funkatron",
	"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title":"Change this title",
	"short_url":"http://example.gim.ie/apf"
}

Notes

Only passed parameters will be updated on the asset. For example, if only the title parameter is passed, tags and privacy will not be affected.

DELETE /asset/:asset_id

Permanently delete an asset. If the asset is not owned by the authenticating user, a 403 Forbidden status is returned

Parameters
Key Type Required Note
asset_id ID / Array True URL path parameter
Example
Request
curl --digest -u USERNAME:ACCESSTOKEN -X DELETE "https://gimmebar.com/api/v0/asset/4da31e56827a9f8404000000"

JSON Response
{
	"deleted":true,
}

GET /assets

Get all assets for the authenticating user. Assets are returned sorted by add date, descending (most recent first).

This method can also take an array of asset_ids. If asset_ids are passed, other parameters are ignored.

Parameters
Key Type Required Note
asset_id ID / Array False If passed, ignores other params. Up to 50 can be passed
type String False See above for valid types
tag String / Array False
private Boolean False Ignored if not provided
limit Integer False Default is 10, Max 50
skip Integer False Default is 0 (first asset)
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/assets"

JSON Response

Note: For brevity we are not listing all the assets returned here

{
	"more_records":true,
	"records":
	[
		{
			"id":"4e10b325827a9fbe04000004",
			"asset_type":"image",
			"content":
			{
				"full":"http://gimmebar.example.com/4e10b31e63433.jpg",
				"display":"http://s3.amazonaws.com/resized-images-new/B00B240F-2005-41B5-A0EF-6AC8823D04D2",
				"stash":"http://s3.amazonaws.com/resized-images-new/9375D3DD-EE48-439F-8367-6F973B490D0C"
			},
			"date":1309717285,
			"media_hash":"f76fc3cd3a5c4415628ed9ae87e7e5d1126927",
			"mime_type":"image/jpeg",
			"private":true,
			"size":126927,
			"source":"upload",
			"description":"#animals I love this pic",
			"tags":
			[
				"animals"
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"Clever Girl",
			"short_url":"http://example.gim.ie/aFM"
		},
		/* more asset objects */
	],
	"total_records":1865,
	"limit":10,
	"skip":0
}

Request
curl -u USERNAME:ACCESSTOKEN -X GET "https://gimmebar.com/api/v0/assets" \
  --data-urlencode "asset_id[]=4d74f3bd827a9ff106000003" \
  --data-urlencode "asset_id[]=4d7f7ab6827a9f7d3200002f" \
  --data-urlencode "asset_id[]=4d9391d5827a9f5b09000002" \
  --data-urlencode "asset_id[]=4d9391f5827a9f0e05000014" \
  --data-urlencode "asset_id[]=4d939287827a9f1105000017" \
  --data-urlencode "asset_id[]=4d9392c1827a9f290600000f" \
  --data-urlencode "asset_id[]=4d949177827a9f7a04000000"

JSON Response
{
	"count":7,
	"records":
	[
		{
			"id":"4d74f3bd827a9ff106000003",
			"asset_type":"page",
			"content":
			{
				"full":"http://gimmebar.example.com/4d74f3bc24c0b.html",
				"original":"http://www.engadget.com/2011/03/07/lenovo-posts-thinkpad-x220-specs-online-includes-ips-display-s/"
			},
			"date":1299510205,
			"media_hash":"24ffbde453065ee2a1c9f0212af1e9a9107",
			"mime_type":"text/html",
			"private":false,
			"size":65356,
			"source":"http://www.engadget.com/2011/03/07/lenovo-posts-thinkpad-x220-specs-online-includes-ips-display-s/",
			"description":"#fooooooooo",
			"tags":
			[
				"fooooooooo"
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"Change this title",
			"short_url":"http://example.gim.ie/apf"
		},
		{
			"id":"4d7f7ab6827a9f7d3200002f",
			"asset_type":"page",
			"content":
			{
				"full":"http://gimmebar.example.com/4d7f7ab5be65e.html",
				"original":"http://www.underconsideration.com/brandnew/archives/perus_new_brand.php"
			},
			"date":1300200118,
			"media_hash":"fd90c1183dbb206653e34db786fac82790839",
			"mime_type":"text/html",
			"private":false,
			"size":90839,
			"source":"http://www.underconsideration.com/brandnew/archives/perus_new_brand.php",
			"description":"#coca",
			"tags":
			[
				"coca"
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"Peru's New Brand - Brand New",
			"short_url":"http://example.gim.ie/apy"
		},
		{
			"id":"4d9391d5827a9f5b09000002",
			"asset_type":"page",
			"content":
			{
				"full":"http://gimmebar.example.com/4d9391d511afe.html",
				"original":"http://funkatron.com/posts.html"
			},
			"date":1301516757,
			"media_hash":"050580af3d976a202faee4441a937b93108564",
			"mime_type":"text/html",
			"private":true,
			"size":108564,
			"source":"http://funkatron.com/posts.html",
			"description":"",
			"tags":
			[
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"I like butts",
			"short_url":"http://example.gim.ie/aqh"
		},
		{
			"id":"4d9391f5827a9f0e05000014",
			"asset_type":"page",
			"content":
			{
				"full":"http://gimmebar.example.com/4d9391d511afe.html",
				"original":"http://funkatron.com/posts.html"
			},
			"date":1301516789,
			"media_hash":"050580af3d976a202faee4441a937b93108564",
			"mime_type":"text/html",
			"private":true,
			"size":108564,
			"source":"http://funkatron.com/posts.html",
			"description":"",
			"tags":
			[
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"I like butts",
			"short_url":"http://example.gim.ie/aqi"
		},
		{
			"id":"4d939287827a9f1105000017",
			"asset_type":"page",
			"content":
			{
				"full":"http://gimmebar.example.com/4d9391d511afe.html",
				"original":"http://funkatron.com/posts.html"
			},
			"date":1301516935,
			"media_hash":"050580af3d976a202faee4441a937b93108564",
			"mime_type":"text/html",
			"private":true,
			"size":108564,
			"source":"http://funkatron.com/posts.html",
			"description":"#bar #baz #foo",
			"tags":
			[
				"bar",
				"baz",
				"foo"
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"I like butts",
			"short_url":"http://example.gim.ie/aqj"
		},
		{
			"id":"4d9392c1827a9f290600000f",
			"asset_type":"text",
			"content":"blammo to all the believers",
			"date":1301516993,
			"media_hash":"c1eb701f2481b154ac25397147d9699827",
			"mime_type":"text/plain",
			"private":true,
			"size":27,
			"source":"http://funkatron.com/posts.html",
			"description":"#bar #baz #foo",
			"tags":
			[
				"bar",
				"baz",
				"foo"
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"poop",
			"short_url":"http://example.gim.ie/aqk"
		},
		{
			"id":"4d949177827a9f7a04000000",
			"asset_type":"image",
			"content":
			{
				"full":"http://gimmebar.example.com/4d949176718fb.jpg"
			},
			"date":1301582199,
			"media_hash":"3c1704bc5bdc58ea8c04727848b439c4120462",
			"mime_type":"image/jpeg",
			"private":true,
			"size":120462,
			"source":"upload",
			"description":"#bar #baz #foo",
			"tags":
			[
				"bar",
				"baz",
				"foo"
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"Test",
			"short_url":"http://example.gim.ie/aql"
		}
	]
}

GET /assets/user/:user_id

Get assets owned by the given user_id. If the requested user_id is different from the authenticating user’s, only public assets will be returned.

This method can also take an array of asset_ids. If asset_ids are passed, other parameters are ignored. If one of the asset_ids requested is not visible to the authenticating user, the method returns a 403 status error.

Parameters
Key Type Required Note
user_id ID True URL path parameter
asset_id ID / Array False
type String False See above for valid types
tag String / Array False
private Boolean False
limit Integer False
skip Integer False
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/assets/user/0529f5c0ab9fbddc90dd7d1f1e101d74"

JSON Response
{
	"more_records":true,
	"records":
	[
		{
			"id":"4e10b325827a9fbe04000004",
			"asset_type":"image",
			"content":
			{
				"full":"http://gimmebar.example.com/4e10b31e63433.jpg",
				"display":"http://s3.amazonaws.com/resized-images-new/B00B240F-2005-41B5-A0EF-6AC8823D04D2",
				"stash":"http://s3.amazonaws.com/resized-images-new/9375D3DD-EE48-439F-8367-6F973B490D0C"
			},
			"date":1309717285,
			"media_hash":"f76fc3cd3a5c4415628ed9ae87e7e5d1126927",
			"mime_type":"image/jpeg",
			"private":true,
			"size":126927,
			"source":"upload",
			"description":"#animals I love this pic",
			"tags":
			[
				"animals"
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"Clever Girl",
			"short_url":"http://example.gim.ie/aFM"
		},
		/* more asset objects */
	],
	"total_records":1865,
	"limit":10,
	"skip":0
}

GET /assets/user/:user_id

Request
curl -u -X GET USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/assets/user/0529f5c0ab9fbddc90dd7d1f1e101d74" \
  --data-urlencode "asset_id[]=4d74f3bd827a9ff106000003"

JSON Response
{
	"count": 1,
	"records": [
		{
			"id": "4d74f3bd827a9ff106000003",
			"asset_type": "page",
			"content": {
				"full": "http://gimmebar.example.com/4d74f3bc24c0b.html",
				"original": "http://www.engadget.com/2011/03/07/lenovo-posts-thinkpad-x220-specs-online-includes-ips-display-s/"
			},
			"date": 1299510205,
			"media_hash": "24ffbde453065ee2a1c9f0212af1e9a9107",
			"mime_type": "text/html",
			"private": false,
			"size": 65356,
			"source": "http://www.engadget.com/2011/03/07/lenovo-posts-thinkpad-x220-specs-online-includes-ips-display-s/",
			"description": "#fooooooooo",
			"tags": [
				"fooooooooo"
			],
			"username": "funkatron",
			"user_id": "0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title": "Change this title",
			"short_url": "http://example.gim.ie/apf"
		}
	]
}

GET /assets/search

Search for assets

Parameters
Key Type Required Note
terms String True
user_id ID False
filter Type String False See above for valid types
limit Integer False
skip Integer False
Example
Request
curl -u USERNAME:ACCESSTOKEN -X GET "https://gimmebar.com/api/v0/assets/search" \
	--data-urlencode "terms=tesla"

JSON Response
{
	"records":
	[
		{
			"id":"4d9f501b827a9fbf040000a5",
			"asset_type":"image",
			"content":
			{
				"full":"http://gimmebar.example.com/4d9f501b7fe5d.jpg",
				"original":"http://www.blogcdn.com/www.engadget.com/media/2011/04/rav4-2011-04-08-600.jpg"
			},
			"date":1302286363,
			"media_hash":"26e184347b47a32c8f31abe3920d978553569",
			"mime_type":"image/jpeg",
			"private":false,
			"size":53569,
			"source":"http://www.engadget.com/",
			"description":"",
			"tags":
			[
			],
			"username":"funkatron",
			"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
			"title":"Engadget\u2019s tesla picture is cool\u00a7",
			"short_url":"http://example.gim.ie/aqm"
		}
	],
	"total_records":1,
	"more_records":false,
	"limit":10,
	"skip":0
}

Collections

GET /collections

Return an array of all collections for authenticating user.

NOTE: When retrieving collections, only the asset_ids that belong to a collection are returned – not each asset object. You can retrieve up to 50 assets at a time with the GET /assets and GET /assets/user/:user_id methods.

Parameters
Key Type Required Note
public_only Boolean False
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/collections"

JSON Response
[
	{
		"id":"4d6d6cf9827a9f7c1000002e",
		"date":1299016953,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"\u9678\u00a7\u00a7!",
		"private":true,
		"slug":"-",
		"short_url":"http://example.gim.ie/apI",
		"assets":
		[
			"b7703f2a12d4c7e1cc2f6999e5be5189",
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000",
			"4dac85f8827a9f5006000000",
			"4dac8748827a9f8304000000",
			"4dac8aa8827a9f5006000021",
			"4dac8d80827a9f410b000000",
			"4dac8db9827a9fd107000001",
			"4dac8e63827a9f410b000002",
			"4dac94f7827a9f6d05000000",
			"4dac955f827a9fab04000000",
			"4dac95a1827a9f6007000000",
			"4dac95df827a9f2708000000",
			"4db06783827a9f9e04000000",
			"4db067e1827a9f7104000000",
			"4dbac514827a9f5331000000",
			"4dc151cb827a9f8104000000",
			"4dc15399827a9f5e05000001",
			"4ddbe459827a9fdd04000000",
			"4de564f8827a9f7e04000000",
			"4de56500827a9f7c04000000",
			"4de56530827a9f7d04000000",
			"4de567f8827a9f7d04000002",
			"4e0dfa6d827a9fc20400007d",
			"4e0dfaa9827a9fe50400002c",
			"4e0dfae5827a9f8f04000034",
			"4e0e07cd827a9f9304000024",
			"4e0e07f9827a9f8f0400004b",
			"4e0e08d1827a9fe504000035",
			"4e0e189b827a9fc20400008c",
			"4e0e189b827a9fe304000020",
			"4e0e206c827a9fcf04000052",
			"4e0e206c827a9fe404000023",
			"4e0e2085827a9ff40400000c",
			"4e0e2085827a9f9004000049",
			"4e0e20b9827a9fe30400002e",
			"4e0e20b9827a9f8f04000056",
			"4e0e20c3827a9fc20400009d",
			"4e0e20c3827a9fe304000037",
			"4e0e2266827a9fe40400003c",
			"4e0e2266827a9fe504000053",
			"4e0e226e827a9f900400004e",
			"4e0e2274827a9ff404000019",
			"4e0e2274827a9f9004000050",
			"4e0e22ab827a9fe304000047",
			"4e0e22ab827a9f8f04000070",
			"4e0e2323827a9fe304000053",
			"4e0e2323827a9ff404000025",
			"4e0e2340827a9fe404000055",
			"4e0e2340827a9f8f0400007d",
			"4e10b31e827a9f8d04000000",
			"4e10b31e827a9f8c04000001",
			"4e10b322827a9fbe04000000",
			"4e10b322827a9f8b04000003",
			"4e10b325827a9f8c04000004",
			"4e10b325827a9f8a0400000d"
		]
	},
	{
		"id":"4d70fdb2827a9f9f5d000000",
		"date":1299250610,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Bonus Score 2",
		"private":false,
		"slug":"bonus-score-2",
		"short_url":"http://example.gim.ie/apG",
		"assets":
		[
			"b7703f2a12d4c7e1cc2f6999e5bab178",
			"b7703f2a12d4c7e1cc2f6999e5b6f632",
			"b7703f2a12d4c7e1cc2f6999e5b7112e",
			"4d7f7ab6827a9f7d3200002f"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000ad",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Books,
		 Movies,
		 & Albums",
		"private":true,
		"slug":"books-movies-albums",
		"short_url":"http://example.gim.ie/apR",
		"assets":
		[
		]
	},
	{
		"id":"4d6d5212827a9f2c56000002",
		"date":1299010066,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"cock blockin' beats!",
		"private":true,
		"slug":"cock-blockin-beats",
		"short_url":"http://example.gim.ie/apH",
		"assets":
		[
			"4dac85f8827a9f5006000000",
			"4dac8748827a9f8304000000",
			"4dac8aa8827a9f5006000021",
			"4dac8d80827a9f410b000000",
			"4dac8db9827a9fd107000001",
			"4dac8e63827a9f410b000002",
			"4dac94f7827a9f6d05000000",
			"4dac955f827a9fab04000000",
			"4dac95a1827a9f6007000000",
			"4dac95df827a9f2708000000",
			"4db06783827a9f9e04000000",
			"4db067e1827a9f7104000000",
			"4dbac514827a9f5331000000",
			"4dc151cb827a9f8104000000",
			"4dc15399827a9f5e05000001",
			"4ddbe459827a9fdd04000000",
			"4de564f8827a9f7e04000000",
			"4de56500827a9f7c04000000",
			"4de56530827a9f7d04000000",
			"4de567f8827a9f7d04000002",
			"4e0e189b827a9fc20400008c",
			"4e0e206c827a9fcf04000052",
			"4e0e2085827a9ff40400000c",
			"4e0e20b9827a9fe30400002e",
			"4e0e20c3827a9fc20400009d",
			"4e0e2266827a9fe40400003c",
			"4e0e226e827a9f900400004e",
			"4e0e2274827a9ff404000019",
			"4e0e22ab827a9fe304000047",
			"4e0e2323827a9fe304000053",
			"4e0e2340827a9fe404000055",
			"4e10b31e827a9f8d04000000",
			"4e10b322827a9fbe04000000",
			"4e10b325827a9f8c04000004"
		]
	},
	{
		"id":"4d92242f827a9fe204000001",
		"date":1301423151,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"foo7",
		"private":true,
		"slug":"foo7",
		"short_url":"http://example.gim.ie/aqa",
		"assets":
		[
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000"
		]
	},
	{
		"id":"4d6d515b827a9f6713000037",
		"date":1299009883,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Foobar",
		"private":false,
		"slug":"foobar",
		"short_url":"http://example.gim.ie/apC",
		"assets":
		[
			"4d8be9a4ab49794635000017",
			"4d8bea8aab4979f23f000003",
			"4d8bf8cbab4979ea66000026",
			"4d8bfaa9ab4979e509000000",
			"4d8bfb0aab49799d6a000034",
			"4d8bff94ab4979cf730000a8",
			"4d8c0559ab4979811d000001",
			"4d8c0812ab4979811d000037",
			"4d8cb806ab4979b54d00003f",
			"4d8cba04ab49798c64000078",
			"4d8ccbcfab4979030f000041"
		]
	},
	{
		"id":"4d7fd17eab497952460000cd",
		"date":1300222334,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Gaming",
		"private":false,
		"slug":"gaming",
		"short_url":"http://example.gim.ie/apS",
		"assets":
		[
			"4d89eb9fab49793510000091",
			"4d8c0812ab4979811d000037",
			"4d8cba04ab49798c64000078",
			"4d949177827a9f7a04000000"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000ab",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Hilarious & Adorable",
		"private":true,
		"slug":"hilarious-adorable",
		"short_url":"http://example.gim.ie/apT",
		"assets":
		[
			"4d7fd2f9ab4979e56500000b",
			"4d80f0d1ab4979cd430000ca"
		]
	},
	{
		"id":"4d70fdf9827a9ff861000000",
		"date":1299250681,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"I like big butts!! I cannot lie!",
		"private":true,
		"slug":"i-like-big-butts-i-cannot-lie",
		"short_url":"http://example.gim.ie/apD",
		"assets":
		[
			"4d74f3bd827a9ff106000003",
			"4d7f7ab6827a9f7d3200002f",
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000aa",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Inspiration",
		"private":true,
		"slug":"inspiration",
		"short_url":"http://example.gim.ie/apU",
		"assets":
		[
			"4d8ccbcfab4979030f000041"
		]
	},
	{
		"id":"4d8925dbab49794f11000061",
		"date":1300833755,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Lafayette",
		"private":false,
		"slug":"lafayette",
		"short_url":"http://example.gim.ie/apV",
		"assets":
		[
			"4d88e5fbab49790751000048"
		]
	},
	{
		"id":"4da33496827a9f800400000d",
		"date":1302541462,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Let&#039;s talk about sports",
		"private":false,
		"slug":"let-039-s-talk-about-sports",
		"short_url":"http://example.gim.ie/aqp",
		"assets":
		[
		]
	},
	{
		"id":"4da335af827a9f8f0500000b",
		"date":1302541743,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Let&#039;s talk about sports 2",
		"private":true,
		"slug":"let-039-s-talk-about-sports-2",
		"short_url":"http://example.gim.ie/aqr",
		"assets":
		[
		]
	},
	{
		"id":"4d7fd173ab4979d25b000002",
		"date":1300222323,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Pinups",
		"private":false,
		"slug":"pinups",
		"short_url":"http://example.gim.ie/apW",
		"assets":
		[
		]
	},
	{
		"id":"4d7faf55827a9ffc7100003b",
		"date":1300213589,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Poop!",
		"private":false,
		"slug":"poop",
		"short_url":"http://example.gim.ie/apE",
		"assets":
		[
			"4d8bf8cbab4979ea66000026",
			"4d8bfaa9ab4979e509000000",
			"4d8bfb0aab49799d6a000034",
			"4d8bff94ab4979cf730000a8",
			"4d8c0559ab4979811d000001",
			"4d8c0812ab4979811d000037",
			"4d8cb806ab4979b54d00003f",
			"4d8cba04ab49798c64000078",
			"4d8ccbcfab4979030f000041",
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000",
			"4d9f501b827a9fbf040000a5"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000ac",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Products I Love",
		"private":true,
		"slug":"products-i-love",
		"short_url":"http://example.gim.ie/apX",
		"assets":
		[
			"4d74f3bd827a9ff106000003",
			"4d7f7ab6827a9f7d3200002f",
			"4dc15399827a9f5e05000001"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000ae",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Recipes",
		"private":true,
		"slug":"recipes",
		"short_url":"http://example.gim.ie/apY",
		"assets":
		[
		]
	}
]

GET /collections/user

Return an array of all collections belonging to the given user_id. If user_id is not the authenticating user, only public collections are returned.

Parameters
Key Type Required Note
user_id ID True
public_only Boolean False if user_id is not the authenticating user, this will be true
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/collections/user?user_id=0529f5c0ab9fbddc90dd7d1f1e101d74"

JSON Response
[
	{
		"id":"4d6d6cf9827a9f7c1000002e",
		"date":1299016953,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"\u9678\u00a7\u00a7!",
		"private":true,
		"slug":"-",
		"short_url":"http://example.gim.ie/apI",
		"assets":
		[
			"b7703f2a12d4c7e1cc2f6999e5be5189",
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000",
			"4dac85f8827a9f5006000000",
			"4dac8748827a9f8304000000",
			"4dac8aa8827a9f5006000021",
			"4dac8d80827a9f410b000000",
			"4dac8db9827a9fd107000001",
			"4dac8e63827a9f410b000002",
			"4dac94f7827a9f6d05000000",
			"4dac955f827a9fab04000000",
			"4dac95a1827a9f6007000000",
			"4dac95df827a9f2708000000",
			"4db06783827a9f9e04000000",
			"4db067e1827a9f7104000000",
			"4dbac514827a9f5331000000",
			"4dc151cb827a9f8104000000",
			"4dc15399827a9f5e05000001",
			"4ddbe459827a9fdd04000000",
			"4de564f8827a9f7e04000000",
			"4de56500827a9f7c04000000",
			"4de56530827a9f7d04000000",
			"4de567f8827a9f7d04000002",
			"4e0dfa6d827a9fc20400007d",
			"4e0dfaa9827a9fe50400002c",
			"4e0dfae5827a9f8f04000034",
			"4e0e07cd827a9f9304000024",
			"4e0e07f9827a9f8f0400004b",
			"4e0e08d1827a9fe504000035",
			"4e0e189b827a9fc20400008c",
			"4e0e189b827a9fe304000020",
			"4e0e206c827a9fcf04000052",
			"4e0e206c827a9fe404000023",
			"4e0e2085827a9ff40400000c",
			"4e0e2085827a9f9004000049",
			"4e0e20b9827a9fe30400002e",
			"4e0e20b9827a9f8f04000056",
			"4e0e20c3827a9fc20400009d",
			"4e0e20c3827a9fe304000037",
			"4e0e2266827a9fe40400003c",
			"4e0e2266827a9fe504000053",
			"4e0e226e827a9f900400004e",
			"4e0e2274827a9ff404000019",
			"4e0e2274827a9f9004000050",
			"4e0e22ab827a9fe304000047",
			"4e0e22ab827a9f8f04000070",
			"4e0e2323827a9fe304000053",
			"4e0e2323827a9ff404000025",
			"4e0e2340827a9fe404000055",
			"4e0e2340827a9f8f0400007d",
			"4e10b31e827a9f8d04000000",
			"4e10b31e827a9f8c04000001",
			"4e10b322827a9fbe04000000",
			"4e10b322827a9f8b04000003",
			"4e10b325827a9f8c04000004",
			"4e10b325827a9f8a0400000d"
		]
	},
	{
		"id":"4d70fdb2827a9f9f5d000000",
		"date":1299250610,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Bonus Score 2",
		"private":false,
		"slug":"bonus-score-2",
		"short_url":"http://example.gim.ie/apG",
		"assets":
		[
			"b7703f2a12d4c7e1cc2f6999e5bab178",
			"b7703f2a12d4c7e1cc2f6999e5b6f632",
			"b7703f2a12d4c7e1cc2f6999e5b7112e",
			"4d7f7ab6827a9f7d3200002f"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000ad",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Books,
		 Movies,
		 & Albums",
		"private":true,
		"slug":"books-movies-albums",
		"short_url":"http://example.gim.ie/apR",
		"assets":
		[
		]
	},
	{
		"id":"4d6d5212827a9f2c56000002",
		"date":1299010066,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"cock blockin' beats!",
		"private":true,
		"slug":"cock-blockin-beats",
		"short_url":"http://example.gim.ie/apH",
		"assets":
		[
			"4dac85f8827a9f5006000000",
			"4dac8748827a9f8304000000",
			"4dac8aa8827a9f5006000021",
			"4dac8d80827a9f410b000000",
			"4dac8db9827a9fd107000001",
			"4dac8e63827a9f410b000002",
			"4dac94f7827a9f6d05000000",
			"4dac955f827a9fab04000000",
			"4dac95a1827a9f6007000000",
			"4dac95df827a9f2708000000",
			"4db06783827a9f9e04000000",
			"4db067e1827a9f7104000000",
			"4dbac514827a9f5331000000",
			"4dc151cb827a9f8104000000",
			"4dc15399827a9f5e05000001",
			"4ddbe459827a9fdd04000000",
			"4de564f8827a9f7e04000000",
			"4de56500827a9f7c04000000",
			"4de56530827a9f7d04000000",
			"4de567f8827a9f7d04000002",
			"4e0e189b827a9fc20400008c",
			"4e0e206c827a9fcf04000052",
			"4e0e2085827a9ff40400000c",
			"4e0e20b9827a9fe30400002e",
			"4e0e20c3827a9fc20400009d",
			"4e0e2266827a9fe40400003c",
			"4e0e226e827a9f900400004e",
			"4e0e2274827a9ff404000019",
			"4e0e22ab827a9fe304000047",
			"4e0e2323827a9fe304000053",
			"4e0e2340827a9fe404000055",
			"4e10b31e827a9f8d04000000",
			"4e10b322827a9fbe04000000",
			"4e10b325827a9f8c04000004"
		]
	},
	{
		"id":"4d92242f827a9fe204000001",
		"date":1301423151,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"foo7",
		"private":true,
		"slug":"foo7",
		"short_url":"http://example.gim.ie/aqa",
		"assets":
		[
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000"
		]
	},
	{
		"id":"4d6d515b827a9f6713000037",
		"date":1299009883,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Foobar",
		"private":false,
		"slug":"foobar",
		"short_url":"http://example.gim.ie/apC",
		"assets":
		[
			"4d8be9a4ab49794635000017",
			"4d8bea8aab4979f23f000003",
			"4d8bf8cbab4979ea66000026",
			"4d8bfaa9ab4979e509000000",
			"4d8bfb0aab49799d6a000034",
			"4d8bff94ab4979cf730000a8",
			"4d8c0559ab4979811d000001",
			"4d8c0812ab4979811d000037",
			"4d8cb806ab4979b54d00003f",
			"4d8cba04ab49798c64000078",
			"4d8ccbcfab4979030f000041"
		]
	},
	{
		"id":"4d7fd17eab497952460000cd",
		"date":1300222334,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Gaming",
		"private":false,
		"slug":"gaming",
		"short_url":"http://example.gim.ie/apS",
		"assets":
		[
			"4d89eb9fab49793510000091",
			"4d8c0812ab4979811d000037",
			"4d8cba04ab49798c64000078",
			"4d949177827a9f7a04000000"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000ab",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Hilarious & Adorable",
		"private":true,
		"slug":"hilarious-adorable",
		"short_url":"http://example.gim.ie/apT",
		"assets":
		[
			"4d7fd2f9ab4979e56500000b",
			"4d80f0d1ab4979cd430000ca"
		]
	},
	{
		"id":"4d70fdf9827a9ff861000000",
		"date":1299250681,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"I like big butts!! I cannot lie!",
		"private":true,
		"slug":"i-like-big-butts-i-cannot-lie",
		"short_url":"http://example.gim.ie/apD",
		"assets":
		[
			"4d74f3bd827a9ff106000003",
			"4d7f7ab6827a9f7d3200002f",
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000aa",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Inspiration",
		"private":true,
		"slug":"inspiration",
		"short_url":"http://example.gim.ie/apU",
		"assets":
		[
			"4d8ccbcfab4979030f000041"
		]
	},
	{
		"id":"4d8925dbab49794f11000061",
		"date":1300833755,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Lafayette",
		"private":false,
		"slug":"lafayette",
		"short_url":"http://example.gim.ie/apV",
		"assets":
		[
			"4d88e5fbab49790751000048"
		]
	},
	{
		"id":"4da33496827a9f800400000d",
		"date":1302541462,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Let&#039;s talk about sports",
		"private":false,
		"slug":"let-039-s-talk-about-sports",
		"short_url":"http://example.gim.ie/aqp",
		"assets":
		[
		]
	},
	{
		"id":"4da335af827a9f8f0500000b",
		"date":1302541743,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Let&#039;s talk about sports 2",
		"private":true,
		"slug":"let-039-s-talk-about-sports-2",
		"short_url":"http://example.gim.ie/aqr",
		"assets":
		[
		]
	},
	{
		"id":"4d7fd173ab4979d25b000002",
		"date":1300222323,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Pinups",
		"private":false,
		"slug":"pinups",
		"short_url":"http://example.gim.ie/apW",
		"assets":
		[
		]
	},
	{
		"id":"4d7faf55827a9ffc7100003b",
		"date":1300213589,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Poop!",
		"private":false,
		"slug":"poop",
		"short_url":"http://example.gim.ie/apE",
		"assets":
		[
			"4d8bf8cbab4979ea66000026",
			"4d8bfaa9ab4979e509000000",
			"4d8bfb0aab49799d6a000034",
			"4d8bff94ab4979cf730000a8",
			"4d8c0559ab4979811d000001",
			"4d8c0812ab4979811d000037",
			"4d8cb806ab4979b54d00003f",
			"4d8cba04ab49798c64000078",
			"4d8ccbcfab4979030f000041",
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000",
			"4d9f501b827a9fbf040000a5"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000ac",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Products I Love",
		"private":true,
		"slug":"products-i-love",
		"short_url":"http://example.gim.ie/apX",
		"assets":
		[
			"4d74f3bd827a9ff106000003",
			"4d7f7ab6827a9f7d3200002f",
			"4dc15399827a9f5e05000001"
		]
	},
	{
		"id":"4d7fc360ab4979f3200000ae",
		"date":1300218720,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Recipes",
		"private":true,
		"slug":"recipes",
		"short_url":"http://example.gim.ie/apY",
		"assets":
		[
		]
	}
]

GET /collections/asset

Return an array of a user’s collections that contain the passed asset_id. If user_id is specified and is different from the authenticating user, only public collections will be returned.

Parameters
Key Type Required Note
asset_id ID True
private Boolean False
user_id ID False
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/collections/asset?asset_id=4d8c0812ab4979811d000037"

JSON Response
[
	{
		"id":"4d6d515b827a9f6713000037",
		"date":1299009883,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Foobar",
		"private":false,
		"slug":"foobar",
		"short_url":"http://example.gim.ie/apC",
		"assets":
		[
			"4d8be9a4ab49794635000017",
			"4d8bea8aab4979f23f000003",
			"4d8bf8cbab4979ea66000026",
			"4d8bfaa9ab4979e509000000",
			"4d8bfb0aab49799d6a000034",
			"4d8bff94ab4979cf730000a8",
			"4d8c0559ab4979811d000001",
			"4d8c0812ab4979811d000037",
			"4d8cb806ab4979b54d00003f",
			"4d8cba04ab49798c64000078",
			"4d8ccbcfab4979030f000041"
		]
	},
	{
		"id":"4d7fd17eab497952460000cd",
		"date":1300222334,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Gaming",
		"private":false,
		"slug":"gaming",
		"short_url":"http://example.gim.ie/apS",
		"assets":
		[
			"4d89eb9fab49793510000091",
			"4d8c0812ab4979811d000037",
			"4d8cba04ab49798c64000078",
			"4d949177827a9f7a04000000"
		]
	},
	{
		"id":"4d7faf55827a9ffc7100003b",
		"date":1300213589,
		"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
		"title":"Poop!",
		"private":false,
		"slug":"poop",
		"short_url":"http://example.gim.ie/apE",
		"assets":
		[
			"4d8bf8cbab4979ea66000026",
			"4d8bfaa9ab4979e509000000",
			"4d8bfb0aab49799d6a000034",
			"4d8bff94ab4979cf730000a8",
			"4d8c0559ab4979811d000001",
			"4d8c0812ab4979811d000037",
			"4d8cb806ab4979b54d00003f",
			"4d8cba04ab49798c64000078",
			"4d8ccbcfab4979030f000041",
			"4d9391d5827a9f5b09000002",
			"4d9391f5827a9f0e05000014",
			"4d939287827a9f1105000017",
			"4d9392c1827a9f290600000f",
			"4d949177827a9f7a04000000",
			"4d9f501b827a9fbf040000a5"
		]
	}
]

GET /collections/slug

Get a single collection by slug for a given user. Either user_id or username must be specified. If user_id is specified and is different from the authenticating user, only public collections will be returned.

Parameters
Key Type Required Note
slug String True
user_id ID False
username String False
Example
Request
curl --digest -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/collections/slug?slug=gaming&username=funkatron"

JSON Response
{
	"id":"4d7fd17eab497952460000cd",
	"date":1300222334,
	"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title":"Gaming",
	"private":false,
	"slug":"gaming",
	"short_url":"http://example.gim.ie/apS",
	"assets":
	[
		"4d89eb9fab49793510000091",
		"4d8c0812ab4979811d000037",
		"4d8cba04ab49798c64000078",
		"4d949177827a9f7a04000000"
	]
}

GET /collection/:collection_id

Get a collection by ID.

Parameters
Key Type Required Note
collection_id ID True URL path parameter
Example
Request
curl -u USERNAME:ACCESSTOKEN "https://gimmebar.com/api/v0/collection/4d70fdb2827a9f9f5d000000"

JSON Response
{
	"id":"4d70fdb2827a9f9f5d000000",
	"date":1299250610,
	"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title":"Bonus Score 2",
	"private":false,
	"slug":"bonus-score-2",
	"short_url":"http://example.gim.ie/apG",
	"assets":
	[
		"b7703f2a12d4c7e1cc2f6999e5bab178",
		"b7703f2a12d4c7e1cc2f6999e5b6f632",
		"b7703f2a12d4c7e1cc2f6999e5b7112e",
		"4d7f7ab6827a9f7d3200002f"
	]
}

POST /collection/:collection_id

Update/change a collection.

Parameters
Key Type Required Note
collection_id ID True URL path parameter
title String False
private Boolean False
Example
Request
curl -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/collection/4d70fdb2827a9f9f5d000000" \
	--data-urlencode "private=false" \
	--data-urlencode "title=Bonus Score 3"

JSON Response
{
	"id":"4d70fdb2827a9f9f5d000000",
	"date":1299250610,
	"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title":"Bonus Score 3",
	"private":false,
	"slug":"bonus-score-3",
	"short_url":"http://example.gim.ie/apG",
	"assets":
	[
		"b7703f2a12d4c7e1cc2f6999e5bab178",
		"b7703f2a12d4c7e1cc2f6999e5b6f632",
		"b7703f2a12d4c7e1cc2f6999e5b7112e",
		"4d7f7ab6827a9f7d3200002f"
	]
}

DELETE /collection/:collection_id

Delete an existing collection

Parameters
Key Type Required Note
collection_id ID True URL path parameter
Example
Request
curl --digest -u USERNAME:ACCESSTOKEN -X DELETE "https://gimmebar.com/api/v0/collection/4d7fd177ab4979f95d000000"

JSON Response
{
	"deleted":true
}

POST /collection

Create a new collection for the authenticating user. Note that collection titles must be unique to the user.

Parameters
Key Type Required Note
title String True
private Boolean False Defaults to TRUE
Example
Request
curl --digest -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/collection" \
	--data-urlencode "title=Let's play some games"

JSON Response
{
	"id": "4e10c61a827a9fcd04000000",
	"date": 1309722138,
	"user_id": "0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title": "Let&#039;s play some games",
	"private": true,
	"slug": "let-039-s-play-some-games",
	"short_url": "http://example.gim.ie/aFO",
	"assets": []
}

POST /collection/:collection_id/add

Add one or more assets to a collection

Parameters
Key Type Required Note
collection_id ID True URL path parameter
asset_id ID / Array True
Example
Request
curl --digest -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/collection/4d7fd177ab4979f95d000000/add" \
	--data-urlencode "asset_id[]=4d8c0812ab4979811d000037"

JSON Response
{
	"assets":
	[
		"4d8a8e8cab4979d12c000004",
		"4d8a8ee3ab49793042000000",
		"4d8c0812ab4979811d000037"
	],
	"date":1300222327,
	"private":false,
	"slug":"bonus-score",
	"short_url":"http://example.gim.ie/apQ",
	"id":"4d7fd177ab4979f95d000000",
	"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title":"Bonus Score"
}

POST /collection/:collection_id/remove

Remove one or more assets from a collection

Parameters
Key Type Required Note
collection_id ID True URL path parameter
asset_id ID / Array True
Example
Request
curl --digest -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/collection/4d7fd177ab4979f95d000000/remove" \
	--data-urlencode "asset_id[]=4d8c0812ab4979811d000037" \
	--data-urlencode "asset_id[]=4d8a8ee3ab49793042000000"

JSON Response
{
	"assets":
	[
		"4d8a8e8cab4979d12c000004"
	],
	"date":1300222327,
	"private":false,
	"slug":"bonus-score",
	"short_url":"http://example.gim.ie/apQ",
	"id":"4d7fd177ab4979f95d000000",
	"user_id":"0529f5c0ab9fbddc90dd7d1f1e101d74",
	"title":"Bonus Score"
}

Tags

GET /tags

Fetch tags for the authenticating user. Returns an array of tag objects

Example
Request
curl --digest -u USERNAME:ACCESSTOKEN -X POST "https://gimmebar.com/api/v0/tags"

JSON Response
[
	{
		"tag":"1920s",
		"count":1
	},
	{
		"tag":"1940s",
		"count":1
	},
	{
		"tag":"1990s",
		"count":2
	},
	{
		"tag":"90s",
		"count":1
	},
	{
		"tag":"Bedrich",
		"count":1
	},
	{
		"tag":"Canada",
		"count":2
	},
	{
		"tag":"ads",
		"count":59
	},
	{
		"tag":"advice",
		"count":1
	},
	{
		"tag":"ajax",
		"count":1
	},
	{
		"tag":"alias",
		"count":1
	},
	{
		"tag":"aljazeera",
		"count":1
	}
]