The API uses OAuth v1.0 for authentication and access to data provided by the API. This documentation will not tell you how to use OAuth, but will give you a brief overview and workflow of how it is used with the API.
OAuth flow description from 3rd party websites:
POST http://api.geekli.st/v1/oauth/request_token
oauth_consumer_key Required String
The consumer key you received from Geeklist when you registered your application.
oauth_callback Optional String
URL to your web application where user's will be sent when done with the authorization step.
oauth_nonce Required String
A random value created from your web application. Must be unique for every request.
oauth_timestamp Required String
A unix epoc timestamp that is used to compare nonce and previous requests. Must be calculated at the time of the request.
oauth_signature Required String
Calculated using all keys being sent to the server.
oauth_token
Used to request users authorization and then their access token.
oauth_token_secret
Used to calculate signature of subsequent requests to validate requests.
GET http://geekli.st/oauth/authorize
oauth_token Required String
The request token returned from step one is sent as a query string parameter when redirecting the user.
oauth_token
The same request token returned from step one.
oauth_verifier
A token verifier used to verify that the authorization step happened successfully.
GET http://api.geekli.st/v1/oauth/access_token
oauth_consumer_key Required String
The consumer key you received from Geeklist when you registered your application.
oauth_token Required String
The request token returned from step one.
oauth_verifier Required String
The verifier token returned from step two.
oauth_nonce Required String
A random value created from your web application. Must be unique for every request.
oauth_timestamp Required String
A unix epoc timestamp that is used to compare nonce and previous requests. Must be calculated at the time of request.
oauth_signature Required String
Calculated using all keys being sent to the server.
oauth_token
Access token that allows you to retrieve or send data as the user from the API
oauth_token_secret
Used to calculate signature of subsequent requests to validate requests.
GET http://api.geekli.st/v1/user
The access token allows you to make requests to the API on behalf of the user.
oauth_consumer_key Required String
The consumer key you received from Geeklist when you registered your application.
oauth_token Required String
The access token returned from step three.
oauth_nonce Required String
A random value created from your web application. Must be unique for every request.
oauth_timestamp Required String
A unix epoc timestamp that is used to compare nonce and previous requests. Must be calculated at the time of request.
oauth_signature Required String
Calculated using all keys being sent to the server.
The difference between this flow and the web application flow is that instead of the Geeklist website redirecting the user back to your application, they are presented with a short code they can manually enter into your application, which you can then use to fetch an access token.
Same as the other work flow, except for below:
oauth_callback Required String
Must set to 'oob' which stands for 'out of band'. This will let the API know that you are requesting from a desktop or mobile application.
This works the same way, except that when the user approves your application, they are given a code to enter into your application and are not redirected.
The code given will be used in place of oauth_verifier in the other work flow.
Same as the other work flow.
Same as the other work flow.
The following methods for accessing and making data within the API is fairly easy to use. For fetching data, it follows a consistent system.
Any methods that are listed as having pagination will accept certain query parameters that allow you to paginate through the results.
Any methods that are listed as having sorting will accept a query parameters that allow you to sort the results by date.
GET http://api.geekli.st/v1/user/cards?page=1
page
Page is the page of results. By default it is 1 and will have as many as there are items to fetch.
GET http://api.geekli.st/v1/user/cards?count=50
count
Count is the amount of items to fetch per page, by default it is 10, but cannot be larger than 50.
GET http://api.geekli.st/v1/user/cards?sort=desc
sort
Sort is the direction to sort by date. By default it is descending.
GET http://api.geekli.st/v1/user
GET http://api.geekli.st/v1/users/:user
{
status: 'ok', // String
data: {
_id: '4e700caae8baed010000042c', // String
bio: 'Javascript and Node.js Evangelist', // String
blog_link: 'http://lepahc.com', // String
created_at: '2011-09-14T02:08:42.978Z', // Date String
email: 'jacob@geekli.st', // String (Private)
is_beta: true, // Boolean
is_featured: false, // Boolean
is_trending: true, // Boolean
location: 'Spokane, WA', // String
name: 'Jacob Chapel', // String
screen_name: 'chapel', // String
social_links: [ // Array [ String ]
'https://geekli.st/chapel'
],
trending_at: '2012-01-12T06:41:00.534Z', // Date String
trending_by: 'csanz', // String
github: {
username: 'chapel' // String
},
stats: {
number_of_cards: 13, // Number
number_of_contributions: 16, // Number
number_of_creds: 140, // Number
number_of_highfives: 714, // Number
number_of_mentions: 0 // Number
},
social: {
twitter_screen_name: 'jacobchapel' // String
},
company: {
name: 'Geeklist', // String
title: 'Software Engineer & API Lead' // String
},
avatar: {
large: 'http://a0.twimg.com/profile_images/2159931135/ava.png', // String
small: 'http://a0.twimg.com/profile_images/2159931135/ava.png' // String
}
}
}GET http://api.geekli.st/v1/user/cards
GET http://api.geekli.st/v1/user/contribs
GET http://api.geekli.st/v1/users/:user/cards
GET http://api.geekli.st/v1/users/:user/contribs
GET http://api.geekli.st/v1/user/cards?featured=true
featured Optional
Returns only featured cards for user (only for cards and not contribs).
{
status: 'ok', // String
data: {
total_cards: 1, // Number
cards: [{
_id: '4f0d1c28df76cb6b5700000e', // String
author_id: '4e700caae8baed010000042c', // String
created_at: '2012-01-11T05:20:40.088Z', // Date String
headline: 'I built the Geekli.st API', // String
is_active: true, // Boolean
is_trending: true, // Boolean
link: 'http://hackers.geekli.st/', // String
permalink: '/chapel/i-built-the-geeklist-api', // String
skills: [ // Array [ String ]
'node.js',
'expressjs',
'mongoose',
'Geekli.st custom MVC framework'
],
slug: 'i-built-the-geeklist-api', // String
tasks: [ // Array [ String ]
'programmed the whole thing',
'built an OAuth v1 server from scratch'
],
trending_at: '2012-01-18T01:52:10.468Z', // Date String
trending_by: 'csanz', // String
trending_hist: [ // Array [ Object ]
{
trending_at: '2012-01-18T01:52:10.468Z', // Date String
trending_by: 'csanz', // String
}
],
updated_at: '2012-08-13T02:35:30.879Z', // Date String
via_app: {
link: 'http://geekli.st', // String
name: 'Geekli.st Test App' // String
},
stats: {
highfives: 57, // Number
views: 1425 // Number
},
short_code: {
gklst_url: 'http://gkl.st/_Slzw' // String
}
}]
}
}GET http://api.geekli.st/v1/cards/:id
{
status: 'ok', // String
data: {
_id: '4f0d1c28df76cb6b5700000e', // String
author_id: '4e700caae8baed010000042c', // String
created_at: '2012-01-11T05:20:40.088Z', // Date String
headline: 'I built the Geekli.st API', // String
is_active: true, // Boolean
is_trending: true, // Boolean
link: 'http://hackers.geekli.st/', // String
permalink: '/chapel/i-built-the-geeklist-api', // String
skills: [ // Array [ String ]
'node.js',
'expressjs',
'mongoose',
'Geekli.st custom MVC framework'
],
slug: 'i-built-the-geeklist-api', // String
tasks: [ // Array [ String ]
'programmed the whole thing',
'built an OAuth v1 server from scratch'
],
trending_at: '2012-01-18T01:52:10.468Z', // Date String
trending_by: 'csanz', // String
trending_hist: [ // Array [ Object ]
{
trending_at: '2012-01-18T01:52:10.468Z', // Date String
trending_by: 'csanz', // String
}
],
updated_at: '2012-08-13T02:35:30.879Z', // Date String
via_app: {
link: 'http://geekli.st', // String
name: 'Geekli.st Test App' // String
},
stats: {
highfives: 57, // Number
views: 1425 // Number
},
short_code: {
gklst_url: 'http://gkl.st/_Slzw' // String
}
has_highfived: false, // Boolean
is_author: true // Boolean
}
}POST http://api.geekli.st/v1/cards
headline Required string
The content of the card.
Returns the card JSON object as if you fetched it.
GET http://api.geekli.st/v1/user/micros
GET http://api.geekli.st/v1/users/:user/micros
{
status: 'ok', // String
data: {
total_micros: 1, // Number
micros: [{
type: 'micro', // String
status: 'Vote now! @gklst #gklst http://instagr.am/p/Ml-jSvn0Px', // String
slug: '20513', // String
permalink: '/chapel/micro/20513', // String
_id: '501b7d2c739c470200000993', // String
trending_at: '2012-08-18T01:52:10.468Z', // Date String
trending_by: 'csanz', // String
trending_hist: [ // Array [ Object ]
{
trending_at: '2012-08-18T01:52:10.468Z', // Date String
trending_by: 'csanz', // String
}
],
updated_at: '2012-08-03T07:26:36.684Z', // Date String
created_at: '2012-08-03T07:26:36.678Z', // Date String
is_active: true, // Boolean
is_trending: false, // Boolean
hashtags: [ // Array [ String ]
'gklst'
],
mentions: [ // Array [ String ]
'4e0fc9695259ad010000024b'
],
via_app: {},
images: {
thumbnail: 'http://distilleryimage9.s3.amazonaws.com/8c_5.jpg', // String
low_res: 'http://distilleryimage9.s3.amazonaws.com/8c_6.jpg', // String
full_size: 'http://distilleryimage9.s3.amazonaws.com/8c_7.jpg', // String
www_url: 'http://instagr.am/p/Ml-jSvn0Px/', // String
photo_id: '226862460443771889_47106999' // String
},
reply: {
in_reply_to: {
id: '501b7d2c739c470200000993', // String
status: 'Vote now! @gklst #gklst http://instagr.am/p/Ml-jSvn0Px', // String
permalink: '/chapel/micro/20513', // String
type: 'micro', // String
is_active: true // Boolean
},
thread: {
id: '501b7d2c739c470200000993', // String
status: 'Vote now! @gklst #gklst http://instagr.am/p/Ml-jSvn0Px', // String
permalink: '/chapel/micro/20513', // String
type: 'micro', // String
is_active: true // Boolean
}
},
stats: {
highfives: 2 // Number
},
short_code: {
gklst_url: 'http://gkl.st/sMrhN' // String
},
user: {
id: '4e700caae8baed010000042c', // String
screen_name: 'chapel', // String
avatar: {
small: 'http://a0.twimg.com/profile_images/2159931135/ava.png', // String
large: 'http://a0.twimg.com/profile_images/2159931135/ava.png' // String
}
}
}]
}
}GET http://api.geekli.st/v1/micros/:id
{
status: 'ok', // String
data: {
type: 'micro', // String
status: 'Vote now! @gklst #gklst http://instagr.am/p/Ml-jSvn0Px', // String
slug: '20513', // String
permalink: '/chapel/micro/20513', // String
_id: '501b7d2c739c470200000993', // String
trending_at: '2012-08-18T01:52:10.468Z', // Date String
trending_by: 'csanz', // String
trending_hist: [ // Array [ Object ]
{
trending_at: '2012-08-18T01:52:10.468Z', // Date String
trending_by: 'csanz', // String
}
],
updated_at: '2012-08-03T07:26:36.684Z', // Date String
created_at: '2012-08-03T07:26:36.678Z', // Date String
is_active: true, // Boolean
is_trending: false, // Boolean
hashtags: [ // Array [ String ]
'gklst'
],
mentions: [ // Array [ String ]
'4e0fc9695259ad010000024b'
],
via_app: {},
images: {
thumbnail: 'http://distilleryimage9.s3.amazonaws.com/8c_5.jpg', // String
low_res: 'http://distilleryimage9.s3.amazonaws.com/8c_6.jpg', // String
full_size: 'http://distilleryimage9.s3.amazonaws.com/8c_7.jpg', // String
www_url: 'http://instagr.am/p/Ml-jSvn0Px/', // String
photo_id: '226862460443771889_47106999' // String
},
reply: {
in_reply_to: {
id: '501b7d2c739c470200000993', // String
status: 'Vote now! @gklst #gklst http://instagr.am/p/Ml-jSvn0Px', // String
permalink: '/chapel/micro/20513', // String
type: 'micro', // String
is_active: true // Boolean
},
thread: {
id: '501b7d2c739c470200000993', // String
status: 'Vote now! @gklst #gklst http://instagr.am/p/Ml-jSvn0Px', // String
permalink: '/chapel/micro/20513', // String
type: 'micro', // String
is_active: true // Boolean
}
},
stats: {
highfives: 2 // Number
},
short_code: {
gklst_url: 'http://gkl.st/sMrhN' // String
},
user: {
id: '4e700caae8baed010000042c', // String
screen_name: 'chapel', // String
avatar: {
small: 'http://a0.twimg.com/profile_images/2159931135/ava.png', // String
large: 'http://a0.twimg.com/profile_images/2159931135/ava.png' // String
}
}
}
} POST http://api.geekli.st/v1/micros
in_reply_to Optional string
The id of the micro being replied to.
status Required string
The content of the micro
Returns the micro JSON object as if you fetched it.
GET http://api.geekli.st/v1/user/links
GET http://api.geekli.st/v1/users/:user/links
{
status: 'ok', // String
data: {
total_links: 1, // Number
links: [{
url: 'http://haridas.in/vim-as-your-ide.html', // String
title: 'Vim as your IDE', // String
description: 'Use Vim as your IDE', // String
slug: '5293', // String
permalink: '/chapel/links/5293', // String
_id: '50270fad2d3cfc0200011122', // String
trending_hist: [],
updated_at: '2012-08-12T11:10:54.950Z', // Date String
created_at: '2012-08-12T02:06:37.692Z', // Date String
is_trending: false, // Boolean
is_active: true, // Boolean
communities: [ // Array [ Object ]
{
name: 'vim', // String
slug: 'vim' // String
}
],
ranking: {
rating: 0, // Number
score: 1, // Number
votes: 1 // Number
},
stats: {
relinks: 0, // Number
clicks: 0, // Number
highfives: 0, // Number
views: 2 // Number
},
user: {
id: '4e700caae8baed010000042c' // String
},
from_link: {
id: '5026a9d72d3cfc020000592e', // String
slug: '5278', // String
title: 'Vim as your IDE', // String
user: {
screen_name: 'FerTo' // String
}
},
category: {
name: 'Vim' // String
}
}]
}
}GET http://api.geekli.st/v1/links
GET http://api.geekli.st/v1/links?communities=javascript
communities Optional
The community you want to see the popular links from.
{
status: 'ok', // String
data: {
links: [{
url: 'http://haridas.in/vim-as-your-ide.html', // String
title: 'Vim as your IDE', // String
description: 'Use Vim as your IDE', // String
slug: '5293', // String
permalink: '/chapel/links/5293', // String
_id: '50270fad2d3cfc0200011122', // String
trending_hist: [],
updated_at: '2012-08-12T11:10:54.950Z', // Date String
created_at: '2012-08-12T02:06:37.692Z', // Date String
is_trending: false, // Boolean
is_active: true, // Boolean
communities: [ // Array [ Object ]
{
name: 'vim', // String
slug: 'vim' // String
}
],
ranking: {
rating: 0, // Number
score: 1, // Number
votes: 1 // Number
},
stats: {
relinks: 0, // Number
clicks: 0, // Number
highfives: 0, // Number
views: 2 // Number
},
user: {
id: '4e700caae8baed010000042c' // String
},
from_link: {
id: '5026a9d72d3cfc020000592e', // String
slug: '5278', // String
title: 'Vim as your IDE', // String
user: {
screen_name: 'FerTo' // String
}
},
category: {
name: 'Vim' // String
}
}]
}
}GET http://api.geekli.st/v1/links/:id
{
status: 'ok', // String
data: {
url: 'http://haridas.in/vim-as-your-ide.html', // String
title: 'Vim as your IDE', // String
description: 'Use Vim as your IDE', // String
slug: '5293', // String
permalink: '/chapel/links/5293', // String
_id: '50270fad2d3cfc0200011122', // String
trending_hist: [],
updated_at: '2012-08-12T11:10:54.950Z', // Date String
created_at: '2012-08-12T02:06:37.692Z', // Date String
is_trending: false, // Boolean
is_active: true, // Boolean
communities: [ // Array [ Object ]
{
name: 'vim', // String
slug: 'vim' // String
}
],
ranking: {
rating: 0, // Number
score: 1, // Number
votes: 1 // Number
},
stats: {
relinks: 0, // Number
clicks: 0, // Number
highfives: 0, // Number
views: 2 // Number
},
user: {
id: '4e700caae8baed010000042c' // String
},
from_link: {
id: '5026a9d72d3cfc020000592e', // String
slug: '5278', // String
title: 'Vim as your IDE', // String
user: {
screen_name: 'FerTo' // String
}
},
category: {
name: 'Vim' // String
}
}
}POST http://api.geekli.st/v1/links
category Optional string
The category to use for the link, defaults to 'My links'.
url Required string
The full url for the link.
title Required string
The title of the link. Max length: 200 characters
description Optional string
The description of the link. Max length: 256 characters
communities Optional array
The communities the link is in.
Returns the link JSON object as if you fetched it.
PUT http://api.geekli.st/v1/links/:id/vote
direction Require string
The direction of the vote, 'up' being positive vote and 'down' being negative vote.
Returns ok if successful.
GET http://api.geekli.st/v1/user/followers
GET http://api.geekli.st/v1/users/:user/followers
GET http://api.geekli.st/v1/user/following
GET http://api.geekli.st/v1/users/:user/following
GET http://api.geekli.st/v1/user/connections
GET http://api.geekli.st/v1/users/:user/connections
The example below is for followers, but is the same for following and connections except total_followers will match the type.
{
status: 'ok', // String
data: {
total_followers: 1, // Number
followers: [{
_id: '4e700caae8baed010000042c', // String
bio: 'Javascript and Node.js Evangelist', // String
blog_link: 'http://lepahc.com', // String
created_at: '2011-09-14T02:08:42.978Z', // Date String
email: 'jacob@geekli.st', // String (Private)
is_beta: true, // Boolean
is_featured: false, // Boolean
is_trending: true, // Boolean
location: 'Spokane, WA', // String
name: 'Jacob Chapel', // String
screen_name: 'chapel', // String
social_links: [ // Array [ String ]
'https://geekli.st/chapel'
],
trending_at: '2012-01-12T06:41:00.534Z', // Date String
trending_by: 'csanz', // String
github: {
username: 'chapel' // String
},
stats: {
number_of_cards: 13, // Number
number_of_contributions: 16, // Number
number_of_creds: 140, // Number
number_of_highfives: 714, // Number
number_of_mentions: 0 // Number
},
social: {
twitter_screen_name: 'jacobchapel' // String
},
company: {
name: 'Geeklist', // String
title: 'Software Engineer & API Lead' // String
},
avatar: {
large: 'http://a0.twimg.com/profile_images/2159931135/ava.png', // String
small: 'http://a0.twimg.com/profile_images/2159931135/ava.png' // String
}
}]
}
}PUT http://api.geekli.st/v1/users/:user/follow
Returns status of 'ok'.
DELETE http://api.geekli.st/v1/users/:user/follow
Returns status of 'ok'.
POST http://api.geekli.st/v1/user/follow
user Required string
The id of the user you want to follow.
action Optional string
The action, if set then you will follow, otherwise will initiate an unfollow.
Returns status of OK.
Activity support pagination like other methods though it has a few features specific to it.
Due to changes on the website, the main feed is now the personal user feed. That means by default the feed you fetch from the API will be the personal feed of the authenticated user. You can of course choose which feed you want to see otherwise, for instance the discovery feed which is every activity.
Please note that the data contained inside of the gfk object changes depending on what type of activity it represents. We will have more detailed breakdown of the different types of activities and the data contained at a later time.
GET http://api.geekli.st/v1/user/activity
GET http://api.geekli.st/v1/users/:user/activity
GET http://api.geekli.st/v1/activity
These parameters are specific to the main activity feeds, specific user activities come as is.
GET http://api.geekli.st/v1/activity?feed=discovery
feed Optional
Specifies which feed to pull data from. By default it uses the authenticated users personal feed. Options include: discovery, at, community
GET http://api.geekli.st/v1/activity?filter=micro
filter Optional
Allows filtering of personal and discovery feeds by activity types. Options include: micro, card, link, highfive, follow, vote, commit
GET http://api.geekli.st/v1/activity?hash=gklst
hash Optional
Hash will give you only micros that contain the hash (#gklst) from the discovery feed.
GET http://api.geekli.st/v1/activity?start=50296ebf2a854bad20000011
start Optional
Since the activity feeds are sorted descending by date, you can specify a starting activity id and fetch any activities older than that id with the limit you set.
{
status: 'ok', // String
data: [{
type: 'micro', // String
_id: '50296ebf2a854bad20000011', // String
updated_at: '2012-08-13T21:16:47.809Z', // Date String
created_at: '2012-08-13T21:16:47.801Z', // Date String
is_active: true, // Boolean
gfk: {
status: 'This is a test', // String
type: 'micro', // String
permalink: '/chapel/micro/20919', // String
id: '50296ebf2a854bad2000000f', // String
reply: {
thread: {
is_active: true, // Boolean
type: 'micro', // Boolean
permalink: '/chapel/micro/20919', // String
status: 'This is a test', // String
id: '50296ebf2a854bad2000000f' // String
},
in_reply_to: {
is_active: true,
type: 'micro',
permalink: '/chapel/micro/20919',
status: 'This is a test',
id: '50296ebf2a854bad2000000f'
}
},
micro: {
type: 'regular' // String
},
via_app: {
name: 'Geekli.st Test App', // String
link: 'http://geekli.st', // String
}
},
user: {
id: '4e700caae8baed010000042c', // String
screen_name: 'chapel', // String
avatar: {
small: 'http://a0.twimg.com/profile_images/2159931135/ava.png', // String
large: 'http://a0.twimg.com/profile_images/2159931135/ava.png' // String
}
}
}]
}You can highfive items such as cards or micros.
POST http://api.geekli.st/v1/highfive
type Required string
The type of item being highfived.
gfk Required string
The id of the item being highfived.
Returns status of OK.