users Endpoint

Overview

The /users endpoint gets a user account's profile information. Individual accounts have the following fields:

Field Description
username The name associated with the account.
type The string "user".
website The first name associated with account.
display_name The name displayed on the UI.
links Resources associated with the account.
created_on The account resource identifier.
location
Where the user is located.

GET the user profile

Gets the public information associated with a user. If the user's profile is private, the caller must be authenticated as the account holder to view this information.  This call takes the following parameter:

Parameter Required Description
username
Yes The user's name.
GET https://bitbucket.org/api/2.0/users/{username}
  Click to expand and view a response...
{
    "username": "tutorials",
    "website": "https://tutorials.bitbucket.org/",
    "display_name": "tutorials account",
    "links": {
        "self": {
            "href": "https://bitbucket.org/!api/2.0/users/tutorials"
        },
        "repositories": {
            "href": "https://bitbucket.org/!api/2.0/repositories/tutorials"
        },
        "html": {
            "href": "https://bitbucket.org/tutorials"
        },
        "followers": {
            "href": "https://bitbucket.org/!api/2.0/users/tutorials/followers"
        },
        "avatar": {
            "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png"
        },
        "following": {
            "href": "https://bitbucket.org/!api/2.0/users/tutorials/following"
        }
    },
    "created_on": "2011-12-20T16:34:07.132459+00:00",
    "location": "Santa Monica, CA",
    "type": "user"
}

GET the list of followers

Gets the list of accounts following the user.  This call takes the following parameters:

Parameter Required Description
username
Yes The user's name.
GET https://bitbucket.org/api/2.0/users/{username}/followers
  Click to expand and view a response...
{
    "pagelen": 10,
    "values": [{
        "username": "tutorials",
        "website": "https://tutorials.bitbucket.org/",
        "display_name": "tutorials account",
        "links": {
            "self": {
                "href": "https://bitbucket.org/!api/2.0/users/tutorials"
            },
            "repositories": {
                "href": "https://bitbucket.org/!api/2.0/repositories/tutorials"
            },
            "html": {
                "href": "https://bitbucket.org/tutorials"
            },
            "followers": {
                "href": "https://bitbucket.org/!api/2.0/users/tutorials/followers"
            },
            "avatar": {
                "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png"
            },
            "following": {
                "href": "https://bitbucket.org/!api/2.0/users/tutorials/following"
            }
        },
        "created_on": "2011-12-20T16:34:07.132459+00:00",
        "location": "Santa Monica, CA",
        "type": "user"
    }],
    "page": 1,
    "size": 1
}

GET a list of accounts the user is following

Gets a list of accounts the user is following. This call takes the following parameters:

Parameter Required Description
username
Yes The user's name.
GET https://bitbucket.org/api/2.0/users/{username}/following
  Click to expand and view a response...
{
  "pagelen": 10,
  "values":  [
     {
      "username": "jdoklovic",
      "kind": "user",
      "website": "http://www.sysbliss.com/",
      "display_name": "Jonathan Doklovic",
      "links":  {
        "self":  {
          "href": "https://api.bitbucket.org/2.0/users/jdoklovic"
        },
        "repositories":  {
          "href": "https://api.bitbucket.org/2.0/users/jdoklovic/repositories"
        },
        "html":  {
          "href": "https://api.bitbucket.org/jdoklovic"
        },
        "followers":  {
          "href": "https://api.bitbucket.org/2.0/users/jdoklovic/followers"
        },
        "avatar":  {
          "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2010/Sep/30/jd_profile_avatar.jpg"
        },
        "following":  {
          "href": "https://api.bitbucket.org/2.0/users/jdoklovic/following"
        }
      },
      "created_on": "2010-09-30T13:44:45.049874+00:00",
      "location": "Minneapolis, MN"
    },
     {
      "username": "atlassian_tutorial",
      "kind": "team",
      "website": "",
      "display_name": "Atlassian Tutorials",
      "links":  {
        "self":  {
          "href": "https://api.bitbucket.org/2.0/teams/atlassian_tutorial"
        },
        "repositories":  {
          "href": "https://api.bitbucket.org/2.0/teams/atlassian_tutorial/repositories"
        },
        "html":  {
          "href": "https://api.bitbucket.org/atlassian_tutorial"
        },
        "followers":  {
          "href": "https://api.bitbucket.org/2.0/teams/atlassian_tutorial/followers"
        },
        "avatar":  {
          "href": "https://secure.gravatar.com/avatar/eb4e0ad6934518b3e335345a4ceeef21?d=https%3A%2F%2Fd3oaxc4q5k2d6q.cloudfront.net%2Fm%2Fbc85d1577e04%2Fimg%2Fdefault_team_avatar%2F32%2Fteam_blue.png&s=32"
        },
        "members":  {
          "href": "https://api.bitbucket.org/2.0/teams/atlassian_tutorial/members"
        },
        "following":  {
          "href": "https://api.bitbucket.org/2.0/teams/atlassian_tutorial/following"
        }
      },
      "created_on": "2011-11-29T05:38:01.075233+00:00",
      "location": ""
    },
     {
      "username": "cat_vasja",
      "kind": "team",
      "website": "",
      "display_name": "cat_vasja",
      "links":  {
        "self":  {
          "href": "https://api.bitbucket.org/2.0/teams/cat_vasja"
        },
        "repositories":  {
          "href": "https://api.bitbucket.org/2.0/teams/cat_vasja/repositories"
        },
        "html":  {
          "href": "https://api.bitbucket.org/cat_vasja"
        },
        "followers":  {
          "href": "https://api.bitbucket.org/2.0/teams/cat_vasja/followers"
        },
        "avatar":  {
          "href": "https://secure.gravatar.com/avatar/e16be80e861baccc5ed4691737faeb05?d=https%3A%2F%2Fd3oaxc4q5k2d6q.cloudfront.net%2Fm%2Fbc85d1577e04%2Fimg%2Fdefault_team_avatar%2F32%2Fteam_blue.png&s=32"
        },
        "members":  {
          "href": "https://api.bitbucket.org/2.0/teams/cat_vasja/members"
        },
        "following":  {
          "href": "https://api.bitbucket.org/2.0/teams/cat_vasja/following"
        }
      },
      "created_on": "2012-10-09T19:45:37.292078+00:00",
      "location": "Deutschland"
    }
  ],
  "page": 1,
  "size": 3
}

GET the user's repositories

Gets the list of the user's repositories. Private repositories only appear on this list if the caller is authenticated and is authorized to view the repository. This call takes the following parameters:

Parameter Required Description
username
Yes The user's name.
GET https://bitbucket.org/api/2.0/repositories/{username}
  Click to expand and view a response...
,
     {
      "scm": "hg",
      "has_wiki": true,
      "description": "This repository is used by the Bitbucket tutorial documentation.  It is referenced from this page:\r\n\r\nhttps://confluence.atlassian.com/display/BITBUCKET/Split+a+Repository+in+Two ",
      "links":  {
        "watchers":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/hgsplitpractice/watchers"
        },
        "commits":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/hgsplitpractice/commits"
        },
        "self":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/hgsplitpractice"
        },
        "html":  {
          "href": "https://api.bitbucket.org/tutorials/hgsplitpractice"
        },
        "avatar":  {
          "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2012/Nov/28/hgsplitpractice-logo-129947197-5_avatar.png"
        },
        "forks":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/hgsplitpractice/forks"
        },
        "clone":  [
           {
            "href": "https://tutorials@bitbucket.org/tutorials/hgsplitpractice",
            "name": "https"
          },
           {
            "href": "ssh://hg@bitbucket.org/tutorials/hgsplitpractice",
            "name": "ssh"
          }
        ],
        "pullrequests":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/hgsplitpractice/pullrequests"
        }
      },
      "fork_policy": "allow_forks",
      "language": "",
      "created_on": "2012-11-27T19:19:33.315067+00:00",
      "full_name": "tutorials/hgsplitpractice",
      "has_issues": false,
      "owner":  {
        "username": "tutorials",
        "display_name": "first name last",
        "links":  {
          "self":  {
            "href": "https://api.bitbucket.org/2.0/users/tutorials"
          },
          "avatar":  {
            "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Jul/17/tutorials-avatar-1826704565-4_avatar.png"
          }
        }
      },
      "updated_on": "2013-02-04T17:04:13.612906+00:00",
      "size": 19065,
      "is_private": false,
      "name": "hgsplitpractice"
    },
     {
      "scm": "git",
      "has_wiki": false,
      "description": "Example scripts using OAuth to connect to Bitbucket. Please contribute more by issuing a Pull Request here!",
      "links":  {
        "watchers":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/oauth-examples/watchers"
        },
        "commits":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/oauth-examples/commits"
        },
        "self":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/oauth-examples"
        },
        "html":  {
          "href": "https://api.bitbucket.org/tutorials/oauth-examples"
        },
        "avatar":  {
          "href": "https://d3oaxc4q5k2d6q.cloudfront.net/m/bc85d1577e04/img/language-avatars/default_16.png"
        },
        "forks":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/oauth-examples/forks"
        },
        "clone":  [
           {
            "href": "https://tutorials@bitbucket.org/tutorials/oauth-examples.git",
            "name": "https"
          },
           {
            "href": "ssh://git@bitbucket.org/tutorials/oauth-examples.git",
            "name": "ssh"
          }
        ],
        "pullrequests":  {
          "href": "https://api.bitbucket.org/2.0/repositories/tutorials/oauth-examples/pullrequests"
        }
      },
      "fork_policy": "allow_forks",
      "language": "",
      "created_on": "2013-04-01T21:19:07.973032+00:00",
      "full_name": "tutorials/oauth-examples",
      "has_issues": false,
      "owner":  {
        "username": "tutorials",
        "display_name": "first name last",
        "links":  {
          "self":  {
            "href": "https://api.bitbucket.org/2.0/users/tutorials"
          },
          "avatar":  {
            "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Jul/17/tutorials-avatar-1826704565-4_avatar.png"
          }
        }
      },
      "updated_on": "2013-04-01T21:20:22.492622+00:00",
      "size": 1794,
      "is_private": false,
      "name": "OAuth Examples"
    },
  ],
  "page": 1,
  "size": 2
}

Was this helpful?

Thanks for your feedback!

33 Archived comments

  1. User avatar

    hadi khosrojerdi

    The user's repositories return error 301.

    Request:

    GET /api/2.0/users/username/repositories



    Response:

    HTTP/1.1 301 MOVED PERMANENTLY

    Content-Language: en
    ETag:"d41d8cd98f00b204e9800998ecf8427e"
    X-Render-Time: 0.0239839553833
    Content-Length:0
    X-Served-By: app13
    Location: https://bitbucket.org/api/2.0/repositories/username
    X-Version: 6e1c93036913
    X-Request-Count:268
    Server:nginx/1.5.3
    X-Content-Type-Options:  nosniff
    X-Frame-Options: SAMEORIGIN
    Strict-Transport-Security:  max-age=2592000
    Date:  Sat, 16 Nov 2013 13:24:18 GMT
    Vary:  Authorization, Accept-Language, Cookie
    X-Static-Version:  f5a36db3429b
    Content-Type: text/html; charset=utf-8


    but this request work.

    GET /api/2.0/repositories/username


     

    16 Nov 2013
    1. User avatar

      Erik van Zijst [Atlassian]

      A 301 is not an error. It merely redirects the client to a different URL. What HTTP client are you using? It should follow 301/302 redirects as per the HTTP spec.

      16 Nov 2013
  2. User avatar

    hadi khosrojerdi

    I use OAuth PHP Client and RestBrowser for my tests.

    Also i have Another Problem for access to public / private repositories of Authenticated Users.

    17 Nov 2013
    1. User avatar

      hadi khosrojerdi

      To OAuth PHP Class it return empty values.

      Request: GET /api/2.0/users/ [owner-username | authenticated-username ] /repositories

      Response:

       {"pagelen": 10, "values": [], "page": 1}

       

      but to restbrowser it return http status code 301.

       

       

       

      17 Nov 2013
      1. User avatar

        Erik van Zijst [Atlassian]

        I'm unable reproduce this (does the user in your URL have any repos at all?).

        Can you raise a support issue by emailing (support@bitbucket.org) details about the actual URL, the user you are authenticating as and if possible a full dump of the wire-level request and response (which includes all the HTTP headers)?

        17 Nov 2013
      1. User avatar

        Erik van Zijst [Atlassian]

        but to restbrowser it return http status code 301.

        301 means a redirect. You should follow the URL in the Location header. Have you tried that? If so, does that return the same 200 status code with empty values list? If so, can you provide a full wire-level capture of the request?

        The wire-level request can be see in the left pane of the restbrowser. Can you provide all headers please?

        21 Nov 2013
        1. User avatar

          hadi khosrojerdi

          301 means a redirect. You should follow the URL in the Location header. Have you tried that?

          Yes, but i think "api/2.0/users/{username}/repositories" is more friendly.(smile)

          23 Nov 2013
  3. User avatar

    hadi khosrojerdi

    I have 2 users:

    Owner : The user which create own application and authenticating by consumer key & consumer secret .

    OAuth_User: The user which authenticating by Owner application .

     

    First Test ( get user repositories ):

    API Version: 2.0

    API URL : https://bitbucket.org/api/2.0/


    Owner

    TesterMethodRequestResponse
    RestbrowserGET/users/owner/repositories
    HTTP/1.1 301 MOVED PERMANENTLY
    PHP OAuth ClassGET/users/owner/repositories
    HTTP/1.1 200 OK
    {"pagelen": 10,"values": [],
    "page": 1
    }

     

    OAuth_User:

    TesterMethodRequestResponse
    RestbrowserGET/api/2.0/users/oauth_user/repositories
    HTTP/1.1 301 MOVED PERMANENTLY
    PHP OAuth ClassGET/api/2.0/users/oauth_user/repositories
    HTTP/1.1 200 OK
    {"pagelen": 10,"values": [],
    "page": 1
    }

    Second Test ( get access to public / private repository ):

    API Version: 2.0

    API URL : https://bitbucket.org/api/2.0/


    Owner:

    TesterMethodRequestResponse
    RestbrowserGET/repositories/owner/private_repo
    HTTP/1.1 200 OK
    {"scm": "git",
    "has_wiki": false,
     ...
    }

    Restbrowser

     

    GET/repositories/owner/public_repo
    HTTP/1.1 200 OK
    {"scm": "git",
    "has_wiki": false,
     ...
    }
    PHP OAuth Class GET /repositories/owner/private_repo
    HTTP/1.1 200 OK
    {"scm": "git",
    "has_wiki": false,
     ...
    }
    PHP OAuth Class GET /repositories/owner/public_repo
    HTTP/1.1 200 OK
    {"scm": "git",
    "has_wiki": false,
     ...
    }


    OAuth_User:

    TesterMethodRequestResponse
    RestbrowserGET/repositories/oauth_user/private_repo
    HTTP/1.1 403 FORBIDDEN

    Restbrowser

    GET/repositories/oauth_user/public_repo
    HTTP/1.1 403 FORBIDDEN

    PHP OAuth Class

    GET/repositories/oauth_user/private_repo
    HTTP/1.1 403 FORBIDDEN

    PHP OAuth Class

    GET/repositories/oauth_user/public_repo
    HTTP/1.1 403 FORBIDDEN




     

     

     

    17 Nov 2013
    1. User avatar

      Erik van Zijst [Atlassian]

      Again, which users are involved? Can you give me the real URLs so I can reproduce the problem?

      Also, this is more of a support case than a documentation comment. Can we move it to the appropriate channel by emailing all the relevant details to: support@bitbucket.org?

      18 Nov 2013
  4. User avatar

    hadi khosrojerdi

    Erik van Zijst [Atlassian] Thanks a lot for helps. (smile)

    Owner = khosroblog

    OAuth_user = rss_samuel

    application-name = khosroblog

    1. rss_samuel is authenticated user from khosroblog application.
    2. khosroblog is authenticated user from khosroblog application.
    3. on the first test both users have problem.( server return empty values ).
    4. on the second test, khosroblog account not access to public / private repository from rss_samuel account.

    I have create a plugin for wordpress and answer to this issue very important for me. also I speak english very hard . (sad)

     

    19 Nov 2013
    1. User avatar

      Erik van Zijst [Atlassian]

      For your php oauth library, can you capture the OAuth authorization header it is sending?

      21 Nov 2013
  5. User avatar

    Anonymous

    Hi, 

    how i can acquire user's profile after successful OAUTH process?

    I have only user's token and secret and no username.

    I tried `/api/2.0/users`  without username - it returns 404;  

    is there endpoint `/api/2.0/user` ?

     

    Or how i should solve this? 

    16 Dec 2013
  6. User avatar

    Timo Sulg

    Ok, found temporary work-around: `/api/1.0/user`.

    Is there any plan to add similar endpoint for api2.0 - it's quite ugly to have methods that uses endpoints from different versions.

    16 Dec 2013
  7. User avatar

    Dillon

    I noticed the data returned for a user in V2 does not contain it's avatar URL unlike V1 where an avatar URL is included. Will the avatar url be added in the future?

    24 Dec 2013
    1. User avatar

      Erik van Zijst [Atlassian]

      Yes, the avatar should be returned (e.g. hit https://api.bitbucket.org/2.0/users/evzijst).

      Or do you mean in other responses where a user shows up as part of a foreign key (e.g. owner in repository)?

      24 Dec 2013
      1. User avatar

        Dillon

        Ah, you know what, I see it's in the "links". My mistake, I over looked it.

        24 Dec 2013
        1. User avatar

          Erik van Zijst [Atlassian]

          No problem!

          24 Dec 2013
  8. User avatar

    Anonymous

    How can I determine the username for the user who authenticated?

    12 Feb 2014
    1. User avatar

      Anonymous

      Bueller?

      11 Mar 2014
  9. User avatar

    Hirakiuchi Daisuke

    Overview describe kind property.

    But `GET the user profile` WebAPI respond the json which contains `type` property , not `kind` property.

    Which property is corrent, `type` or `kind` ?

    05 Aug 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Good day Hirakiuchi,

      The correct property is 'type' I have fixed this on the page and in most of the examples.

      Thank you for taking the time to comment and helping us make these better. 

      Dan

       

      11 Aug 2014
  10. User avatar

    Yong Gu

    Is there an api in Version 2 that 'Gets the details of the repositories that the user owns or has at least read access to. Use this if you're looking for a full list of all of the repositories associated with a user.'? The api does exist in Version 1 but in Version 2, i can only find the api that returns the owned repositories. 

    I want to get the whole list of the repositories that the user can access. Is there any way to do this? Thanks for any advice.

    29 Oct 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Good day Yong,

      Thanks for taking the time to comment.

      I need to update this in the docs but you can use the following:

      This should return the result you're seeking.

      I hope this helps, I'll get at updates to reflect this in the docs.

      Happy coding,

      Dan

      30 Oct 2014
      1. User avatar

        Erik van Zijst [Atlassian]

        To elaborate on that a little, there are 4 different roles:

        • member – all repositories you have explicit access to (somebody gave you read/write on it), or are owned by a team that you are a member of;
        • contributor – all repositories you can push to;
        • admin – all repositories you can administer;
        • owner – all repositories owned by you

        The role parameter can be used on any /repositories URL and it will just filter down the result. For instance, if I start with:

            GET /2.0/repositories/atlassian

        Then I get all of Atlassian's repositories that I can see (public, or those I have read/write/admin on). I can filter that down to return just the ones I can write to:

            GET /2.0/repositories/atlassian?role=contributor

        This filters the list down to those repo I have write or admin access on.

        If you do not specify a role, then no post-filtering takes place and you get the full list of repos under the URL. For the base URL:

            GET /2.0/repositories

        This means you get absolutely all repositories you can see on Bitbucket. This includes all public repositories, combined with all your own and your teams' private repositories

        Hope that helps.

        30 Oct 2014
        1. User avatar

          Kristopher Wilson

          Yeah, this doesn't seem to work. With member, I still just get the repos owned by the user, and if I try collaborator, I get "Unsupported value for role: collaborator"

          22 Nov 2014
          1. User avatar

            Erik van Zijst [Atlassian]

            My bad. It's contributor instead of collaborator:

            https://api.bitbucket.org/2.0/repositories/?role=contributor

            25 Nov 2014
            1. User avatar

              Sruti Harikumar

              This doesn't seem to work. I get no repositories whatsoever for role=member or role=contributor, although I'm part of a team that has over 20 repositories and I can push to the projects.

              {
              "pagelen": 10,
              "values": [],
              "page": 1
              }

              21 Jul 2015
              1. User avatar

                Erik van Zijst [Atlassian]

                Are you logged in? Failing to send credentials will result in an empty set. Note that the api.bitbucket.org domain does not issue session cookies, meaning that your browser will not authenticate, even if you're logged into bitbucket.org.

                Could you paste the command you ran?

                21 Jul 2015
                1. User avatar

                  Sruti Harikumar

                  Yes I'm sending my Authorization header with the bearer token

                  https://api.bitbucket.org/2.0/repositories/myusername?role=member

                  Authorization: Bearer token

                  I know that I'm authenticated because i'm able to fetch results for this api call

                  https://api.bitbucket.org/2.0/users/myusername

                  Authorization: Bearer token

                  21 Jul 2015
                  1. User avatar

                    Erik van Zijst [Atlassian]

                    I know that I'm authenticated because i'm able to fetch results for this api call

                    That's a public API and will always return user info. To verify you are authenticating, hit https://api.bitbucket.org/2.0/user instead. It should return your user object.

                    21 Jul 2015
                    1. User avatar

                      Sruti Harikumar

                      Yes. That returns my user info  in the form

                      {
                      "username": "",
                      "website": "",
                      "display_name": "",
                      "uuid": "{}",
                      "links": {
                      "hooks": {
                      "href": "https://api.bitbucket.org/2.0/users/username/hooks"
                      },
                      "self": {
                      "href": "https://api.bitbucket.org/2.0/users/username"
                      },
                      "repositories": {
                      "href": "https://api.bitbucket.org/2.0/repositories/username"
                      },
                      "html": {
                      "href": "https://bitbucket.org/username"
                      },
                      "followers": {
                      "href": "https://api.bitbucket.org/2.0/users/username/followers"
                      },
                      "avatar": {
                      "href": "https://bitbucket.org/account/username/avatar/32/"
                      },
                      "following": {
                      "href": "https://api.bitbucket.org/2.0/users/username/following"
                      }
                      },
                      "created_on": "2014-11-24T22:10:09.466213+00:00",
                      "location": "San Francisco, CA",
                      "type": "user"
                      }

                      21 Jul 2015
                      1. User avatar

                        Erik van Zijst [Atlassian]

                        Let's move this to support and get you sorted. Can you click "Technical Support" on https://bitbucket.org/support and create a ticket?

                        Please paste the actual commands you ran (not just the response) and mention my name for speedy follow up.

                        21 Jul 2015
                  1. User avatar

                    Erik van Zijst [Atlassian]

                    By the way, https://api.bitbucket.org/2.0/repositories/myusername is the collection of your own repos. Not you teams'. So if you have no personal repos at all, then filtering this list down further is still not going to return anything.

                    If team repos is what you are expecting to see, you should really hit https://api.bitbucket.org/2.0/repositories/?role=memberinstead. Have a look at the documentation for those endpoints.

                    21 Jul 2015
Powered by Confluence and Scroll Viewport