Users API

API for accessing and modifying user information.

Searching for Users

The route for user searching is:

  /user/search/:search

For instance, you would search for users with 'chacon' in their name like this:

$ curl -i http://github.com/api/v2/xml/user/search/chacon

You can also search by email address. This only matches against the email address the user has listed on their public profile, and is opt-in for everyone.

$ curl -i http://github.com/api/v2/xml/user/email/user@email.com

Getting User Information

You can then get extended information on users by their username. The url format is:

  /user/show/:username [GET]

so the following command

$ curl http://github.com/api/v2/json/user/show/defunkt
{
  "user": {
    "gravatar_id": "b8dbb1987e8e5318584865f880036796",
    "company": "GitHub",
    "name": "Chris Wanstrath",
    "created_at": "2007/10/19 22:24:19 -0700",
    "location": "San Francisco, CA",
    "public_repo_count": 98,
    "public_gist_count": 270,
    "blog": "http://chriswanstrath.com/",
    "following_count": 196,
    "id": 2,
    "type": "User",
    "permission": null,
    "followers_count": 1692,
    "login": "defunkt",
    "email": "chris@wanstrath.com"
  }
}

If you authenticated as that user, you will also get this information:

  total_private_repo_count: 1
  collaborators: 3
  disk_usage: 50384
  owned_private_repo_count: 1
  private_gist_count: 0
  plan:
    name: mega
    collaborators: 60
    space: 20971520
    private_repos: 125

If you authenticate, you can also get your own information by leaving your username out.

/user/show [GET]

You can use the following command to get your information:

$ curl http://github.com/api/v2/json/user/show?login=defunkt&token=XXX

curl -F issues a POST request, which won't work.

Authenticated User Management

If you are authenticated, you can update your users information by POSTing to it in a few different ways.

  /user/show/:username [POST]

      :values[key] = value

Where the POST values are of:

• name
• email
• blog
• company
• location

So, you could do this to update your email address:

$ curl -F 'login=schacon' -F 'token=XXX' https://github.com/api/v2/json/user/show/schacon -F 'values[email]=scott@geemail.com'
{
  "user": {
    "company": "Logical Awesome",
    "name": "Scott Chacon",
    "blog": "http:\/\/jointheconversation.org",
    "disk_usage": 89352,
    "collaborators": 3,
    ...
    "email": "scott@geemail.com",
    "location": "Redwood City, CA"
    "created_at": "2008-01-27T09:19:28-08:00",
  }
}

Following Network

If you want to look at the following network on GitHub, you can request the users that a specific user is following with:

/user/show/:user/following

or the users following a specific user with:

/user/show/:user/followers

For example, if you want to see which users are following 'defunkt', you can run this:

$ curl -i http://github.com/api/v2/json/user/show/defunkt/followers

If you are authenticated as a user, you can also follow or unfollow users with:

/user/follow/:user [POST]

/user/unfollow/:user [POST]

Watched Repos

To see which repositories a user is watching, you can call:

/repos/watched/:user

For example,

$ curl http://github.com/api/v2/json/repos/watched/schacon
{
  "repositories": [
    {
      "url": "https://github.com/mojombo/grit",
      "homepage": "http://grit.rubyforge.org/",
      "watchers": 816,
      "created_at": "2007/10/29 07:37:16 -0700",
      "has_wiki": true,
      "pushed_at": "2010/12/19 05:36:51 -0800",
      "fork": false,
      "open_issues": 32,
      "private": false,
      "name": "grit",
      "description": "Grit gives you object oriented read/write access to Git repositories via Ruby.",
      "owner": "mojombo",
      "has_issues": true,
      "forks": 119,
      "has_downloads": true
    }
  ]
}

Public Key Management

  /user/keys

  /user/key/add [POST]
      :title
      :key

  /user/key/remove [POST]
      :id

Email Address Management

  /user/emails [GET]

  /user/email/add [POST]

  /user/email/remove [POST]