Skip to content


Subversion checkout URL

You can clone with
Download ZIP
octo.js - A small JavaScript library for GitHub's API that works in nodejs and the browser.
JavaScript CoffeeScript
Latest commit fbef7ee @Caged Merge pull request #17 from Caged/update-deps
Update dependencies
Failed to load latest commit information.
docs update docco docs
examples update express, connect and tests
test/browser update express, connect and tests
.gitignore add examples directory and a couple examples to start
Makefile more idiomatic CoffeeScript examples in the README
component.json bump version
examples.js move index.js to examples.js
octo.js syntax tweaks
octo.min.js recompile the min version
package.json update express, connect and tests


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 #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'/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
Something went wrong with that request. Please try again.