REST API endpoints for users
Use the REST API to get public and private information about authenticated users.
Get the authenticated user
OAuth app tokens and personal access tokens (classic) need the user
scope in order for the response to include private profile information.
Fine-grained access tokens for "Get the authenticated user"
This endpoint works with the following fine-grained token types:
The fine-grained token does not require any permissions.
HTTP response status codes for "Get the authenticated user"
Status code | Description |
---|---|
200 | OK |
304 | Not modified |
401 | Requires authentication |
403 | Forbidden |
Code samples for "Get the authenticated user"
Request examples
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/user
Response with public and private profile information
Status: 200
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/octocat/received_events",
"type": "User",
"site_admin": false,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z",
"private_gists": 81,
"total_private_repos": 100,
"owned_private_repos": 100,
"disk_usage": 10000,
"collaborators": 8,
"two_factor_authentication": true,
"plan": {
"name": "Medium",
"space": 400,
"private_repos": 20,
"collaborators": 0
}
}
Update the authenticated user
Note: If your email is set to private and you send an email
parameter as part of this request to update your profile, your privacy settings are still enforced: the email address will not be displayed on your public profile or via the API.
Fine-grained access tokens for "Update the authenticated user"
This endpoint works with the following fine-grained token types:
The fine-grained token must have the following permission set:
- "Profile" user permissions (write)
Parameters for "Update the authenticated user"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
name string The new name of the user. |
email string The publicly visible email address of the user. |
blog string The new blog URL of the user. |
twitter_username string or null The new Twitter username of the user. |
company string The new company of the user. |
location string The new location of the user. |
hireable boolean The new hiring availability of the user. |
bio string The new short biography of the user. |
HTTP response status codes for "Update the authenticated user"
Status code | Description |
---|---|
200 | OK |
304 | Not modified |
401 | Requires authentication |
403 | Forbidden |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Update the authenticated user"
Request example
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/user \
-d '{"blog":"https://github.com/blog","name":"monalisa octocat"}'
Response
Status: 200
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/octocat/received_events",
"type": "User",
"site_admin": false,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z",
"private_gists": 81,
"total_private_repos": 100,
"owned_private_repos": 100,
"disk_usage": 10000,
"collaborators": 8,
"two_factor_authentication": true,
"plan": {
"name": "Medium",
"space": 400,
"private_repos": 20,
"collaborators": 0
}
}
Get a user using their ID
Provides publicly available information about someone with a GitHub account. This method takes their durable user ID
instead of their login
, which can change over time.
The email
key in the following response is the publicly visible email address from your GitHub Enterprise Server profile page. When setting up your profile, you can select a primary email address to be “public” which provides an email entry for this endpoint. If you do not set a public email address for email
, then it will have a value of null
. You only see publicly visible email addresses when authenticated with GitHub Enterprise Server. For more information, see Authentication.
The Emails API enables you to list all of your email addresses, and toggle a primary email to be visible publicly. For more information, see "Emails API".
Parameters for "Get a user using their ID"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
account_id integer Requiredaccount_id parameter |
HTTP response status codes for "Get a user using their ID"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples for "Get a user using their ID"
Request examples
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/user/ACCOUNT_ID
Default response
Status: 200
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/octocat/received_events",
"type": "User",
"site_admin": false,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"twitter_username": "monatheoctocat",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z"
}
List users
Lists all users, in the order that they signed up on GitHub Enterprise Server. This list includes personal user accounts and organization accounts.
Note: Pagination is powered exclusively by the since
parameter. Use the Link header to get the URL for the next page of users.
Fine-grained access tokens for "List users"
This endpoint works with the following fine-grained token types:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token does not require any permissions.
This endpoint can be used without authentication if only public resources are requested.
Parameters for "List users"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
since integer A user ID. Only return users with an ID greater than this ID. |
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
HTTP response status codes for "List users"
Status code | Description |
---|---|
200 | OK |
304 | Not modified |
Code samples for "List users"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/users
Response
Status: 200
[
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/octocat/received_events",
"type": "User",
"site_admin": false
}
]
Get a user
Provides publicly available information about someone with a GitHub account.
The email
key in the following response is the publicly visible email address from your GitHub Enterprise Server profile page. When setting up your profile, you can select a primary email address to be “public” which provides an email entry for this endpoint. If you do not set a public email address for email
, then it will have a value of null
. You only see publicly visible email addresses when authenticated with GitHub Enterprise Server. For more information, see Authentication.
The Emails API enables you to list all of your email addresses, and toggle a primary email to be visible publicly. For more information, see "Emails API".
Parameters for "Get a user"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
username string RequiredThe handle for the GitHub user account. |
HTTP response status codes for "Get a user"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples for "Get a user"
Request examples
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/users/USERNAME
Default response
Status: 200
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/octocat/received_events",
"type": "User",
"site_admin": false,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"twitter_username": "monatheoctocat",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z"
}
Get contextual information for a user
Provides hovercard information. You can find out more about someone in relation to their pull requests, issues, repositories, and organizations.
The subject_type
and subject_id
parameters provide context for the person's hovercard, which returns more information than without the parameters. For example, if you wanted to find out more about octocat
who owns the Spoon-Knife
repository, you would use a subject_type
value of repository
and a subject_id
value of 1300192
(the ID of the Spoon-Knife
repository).
OAuth app tokens and personal access tokens (classic) need the repo
scope to use this endpoint.
Fine-grained access tokens for "Get contextual information for a user"
This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.
Parameters for "Get contextual information for a user"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
username string RequiredThe handle for the GitHub user account. |
Name, Type, Description |
---|
subject_type string Identifies which additional information you'd like to receive about the person's hovercard. Can be Can be one of: |
subject_id string Uses the ID for the |
HTTP response status codes for "Get contextual information for a user"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Get contextual information for a user"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/users/USERNAME/hovercard
Response
Status: 200
{
"contexts": [
{
"message": "Owns this repository",
"octicon": "repo"
}
]
}