octo.js - A small JavaScript library for GitHub's API that works in nodejs and the browser.
JavaScript CoffeeScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
docs update docco docs Apr 28, 2012
examples update express, connect and tests Dec 23, 2012
test/browser update express, connect and tests Dec 23, 2012
.gitignore add examples directory and a couple examples to start Apr 15, 2012
Makefile use no-mangle when uglifying Jun 10, 2012
Readme.md more idiomatic CoffeeScript examples in the README Sep 20, 2012
component.json bump version Sep 10, 2012
examples.js move index.js to examples.js Jul 7, 2012
octo.min.js recompile the min version Jul 22, 2012
package.json update express, connect and tests Dec 23, 2012



Octo.js is a simple, flexible, functional JavaScript library for interacting with GitHub's v3 API. It runs in node.js apps and the browser. It supports Basic Auth, OAuth 2, pagination and more.

Requires superagent — A lightweight library for supporting Ajax in the browser and HTTP in node.js.

All examples are written in CoffeeScript, but Octo.js itself is written in JavaScript.

Quick Example

api = octo.api()
do api.get('/events').on 'success', (res) ->
  pubevents = res.body

api.get sets up a closure, so you'll need to invoke it before the request is sent.

events = api.get('/events').perpage(50)
  .on 'end', (res) ->
    console.log api.limit()
    console.log events.page() #1

do events

Using in the browser

Download both superagent and octo.js and include them in the <head> of your document.

  <script src="superagent.js"></script>
  <script src="octo.js"></script>

Using in node.js

Install using npm.

npm install octo

Require octo in your node.js script

octo = require 'octo'


One goal of octo.js was to make paging very simple. Paging is built right into the library.

events = api.get('/events').on 'success', (res) ->
  # the current page

  # requests the next page

  # requests the previous page

do events

What if you want to start on a different page and limit the number of results per page?

# Start on page 5 only returning 10 results per page
do api.get('/events').page(5).perpage(10)


Octo.js supports three events: "success", "error" and "end". These callbacks are registered per pager. This makes it easy to use the same callbacks for each page you request.

  • success - Response status was in the 200 range
  • error - Response wasn't in the 200 range
  • end - Fired at the end of every request, regarldess of status.
do api.get('/events')
  .on('success', (res) -> console.log(res.body))
  .on('error', (res) -> console.log(res.body))
  .on('end', (res) -> console.log(res.body))

Basic Auth

api = octo.api().username('foo').password('bar')
do api.get('/user').on 'success', (res) -> console.log res.body


If you've registered your script or app as an OAuth app, you can use your token to authenticate with the api.

api = octo.api().token('MY APP TOKEN')
do api.get('/user').on 'success', (res) -> console.log res.body

This will work with any registered OAuth application, but will return unauthorized if you've not registered your application with GitHub.

Getting an OAuth 2 token from the API

GitHub APIv3 allows you to programmatically fetch a token for use in scripts that might not be websites. Grabbing an OAuth token requires a username and password. Once you have a token, you can use it without a need for your username and password.

api = octo.api().username('foo').password('bar')
do api.post('/authorizations', {note: 'my script', scopes: ['public_repo']})
   .on 'success', (res) -> console.log res.body

Checking Rate limits

The GitHub API has a rate limit that's returned with the headers of every request. You can easily access this info to see your limit and how many requests you have left

do api.get('/users/caged/repos').on 'success', ->
  # Your limit per hour
  console.log api.limit()

  # Amount you have remaining in that hour
  console.log api.remaining()

More examples

There are some interactive examples in ./examples. You can fire up the server to play with these:

node examples.js
Examples available at http://localhost:9292