Users API Reference

Get the authenticated user

GET /user

OAuth app tokens and personal access tokens (classic) need the user scope in order for the response to include private profile information.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

Update the authenticated user

PATCH /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.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes
422	Validation failed, or the endpoint has been spammed.	yes

List users blocked by the authenticated user

GET /user/blocks

List the users you've blocked on your personal account.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Check if a user is blocked by the authenticated user

GET /user/blocks/{username}

Returns a 204 if the given user is blocked by the authenticated user. Returns a 404 if the given user is not blocked by the authenticated user, or if the given user account has been identified as spam by GitHub.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	If the user is blocked	no
404	If the user is not blocked	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

Block a user

PUT /user/blocks/{username}

Blocks the given user and returns a 204. If the authenticated user cannot block the given user a 422 is returned.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	Response	no
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes
422	Validation failed, or the endpoint has been spammed.	yes

Unblock a user

DELETE /user/blocks/{username}

Unblocks the given user and returns a 204.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	Response	no
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes
404	Resource not found	yes

Set primary email visibility for the authenticated user

PATCH /user/email/visibility

Sets the visibility for your primary email addresses.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes
422	Validation failed, or the endpoint has been spammed.	yes

List email addresses for the authenticated user

GET /user/emails

Lists all of your email addresses, and specifies which one is visible

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Add an email address for the authenticated user

POST /user/emails

OAuth app tokens and personal access tokens (classic) need the user scope to use this endpoint.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
201	Response	yes
422	Validation failed, or the endpoint has been spammed.	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Delete an email address for the authenticated user

DELETE /user/emails

OAuth app tokens and personal access tokens (classic) need the user scope to use this endpoint.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
204	Response	no
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes
422	Validation failed, or the endpoint has been spammed.	yes

List followers of the authenticated user

GET /user/followers

Lists the people following the authenticated user.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

List the people the authenticated user follows

GET /user/following

Lists the people who the authenticated user follows.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

Check if a person is followed by the authenticated user

GET /user/following/{username}

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	if the person is followed by the authenticated user	no
404	if the person is not followed by the authenticated user	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

Follow a user

PUT /user/following/{username}

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	Response	no
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes
422	Validation failed, or the endpoint has been spammed.	yes

Unfollow a user

DELETE /user/following/{username}

OAuth app tokens and personal access tokens (classic) need the user:follow scope to use this endpoint.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	Response	no
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

List GPG keys for the authenticated user

GET /user/gpg_keys

Lists the current user's GPG keys.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Create a GPG key for the authenticated user

POST /user/gpg_keys

Adds a GPG key to the authenticated user's GitHub account.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
201	Response	yes
422	Validation failed, or the endpoint has been spammed.	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Get a GPG key for the authenticated user

GET /user/gpg_keys/{gpg_key_id}

View extended details for a single GPG key.

Parameters

Name	In	Required	Description
`gpg_key_id`	path	yes	The unique identifier of the GPG key.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

Delete a GPG key for the authenticated user

DELETE /user/gpg_keys/{gpg_key_id}

Removes a GPG key from the authenticated user's GitHub account.

Parameters

Name	In	Required	Description
`gpg_key_id`	path	yes	The unique identifier of the GPG key.

Responses

Status	Description	Has JSON body
204	Response	no
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

List public SSH keys for the authenticated user

GET /user/keys

Lists the public SSH keys for the authenticated user's GitHub account.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Create a public SSH key for the authenticated user

POST /user/keys

Adds a public SSH key to the authenticated user's GitHub account.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
201	Response	yes
422	Validation failed, or the endpoint has been spammed.	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Get a public SSH key for the authenticated user

GET /user/keys/{key_id}

View extended details for a single public SSH key.

Parameters

Name	In	Required	Description
`key_id`	path	yes	The unique identifier of the key.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

Delete a public SSH key for the authenticated user

DELETE /user/keys/{key_id}

Removes a public SSH key from the authenticated user's GitHub account.

Parameters

Name	In	Required	Description
`key_id`	path	yes	The unique identifier of the key.

Responses

Status	Description	Has JSON body
204	Response	no
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

List public email addresses for the authenticated user

GET /user/public_emails

Lists your publicly visible email address, which you can set with the

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

List social accounts for the authenticated user

GET /user/social_accounts

Lists all of your social accounts.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Add social accounts for the authenticated user

POST /user/social_accounts

Add one or more social accounts to the authenticated user's profile.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
201	Response	yes
422	Validation failed, or the endpoint has been spammed.	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Delete social accounts for the authenticated user

DELETE /user/social_accounts

Deletes one or more social accounts from the authenticated user's profile.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
204	Response	no
422	Validation failed, or the endpoint has been spammed.	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

List SSH signing keys for the authenticated user

GET /user/ssh_signing_keys

Lists the SSH signing keys for the authenticated user's GitHub account.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Create a SSH signing key for the authenticated user

POST /user/ssh_signing_keys

Creates an SSH signing key for the authenticated user's GitHub account.

Parameters

No parameters.

Responses

Status	Description	Has JSON body
201	Response	yes
422	Validation failed, or the endpoint has been spammed.	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Get an SSH signing key for the authenticated user

GET /user/ssh_signing_keys/{ssh_signing_key_id}

Gets extended details for an SSH signing key.

Parameters

Name	In	Required	Description
`ssh_signing_key_id`	path	yes	The unique identifier of the SSH signing key.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes
304	Not modified	no
403	Forbidden	yes
401	Requires authentication	yes

Delete an SSH signing key for the authenticated user

DELETE /user/ssh_signing_keys/{ssh_signing_key_id}

Deletes an SSH signing key from the authenticated user's GitHub account.

Parameters

Name	In	Required	Description
`ssh_signing_key_id`	path	yes	The unique identifier of the SSH signing key.

Responses

Status	Description	Has JSON body
204	Response	no
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes
401	Requires authentication	yes

Get a user using their ID

GET /user/{account_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.

Parameters

Name	In	Required	Description
`account_id`	path	yes	account_id parameter

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes

List users

GET /users

Lists all users, in the order that they signed up on GitHub. This list includes personal user accounts and organization accounts.

Parameters

Name	In	Required	Description
`since`	query	no	A user ID. Only return users with an ID greater than this ID.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no

Get a user

GET /users/{username}

Provides publicly available information about someone with a GitHub account.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes

List attestations by bulk subject digests

POST /users/{username}/attestations/bulk-list

List a collection of artifact attestations associated with any entry in a list of subject digests owned by a user.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`before`	query	no	A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API."
`after`	query	no	A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API."
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
200	Response	yes

Delete attestations in bulk

POST /users/{username}/attestations/delete-request

Delete artifact attestations in bulk by either subject digests or unique ID.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
200	Response	no
404	Resource not found	yes

Delete attestations by subject digest

DELETE /users/{username}/attestations/digest/{subject_digest}

Delete an artifact attestation by subject digest.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`subject_digest`	path	yes	Subject Digest

Responses

Status	Description	Has JSON body
200	Response	no
204	Response	no
404	Resource not found	yes

Delete attestations by ID

DELETE /users/{username}/attestations/{attestation_id}

Delete an artifact attestation by unique ID that is associated with a repository owned by a user.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`attestation_id`	path	yes	Attestation ID

Responses

Status	Description	Has JSON body
200	Response	no
204	Response	no
403	Forbidden	yes
404	Resource not found	yes

List attestations

GET /users/{username}/attestations/{subject_digest}

List a collection of artifact attestations with a given subject digest that are associated with repositories owned by a user.

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`before`	query	no	A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API."
`after`	query	no	A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API."
`username`	path	yes	The handle for the GitHub user account.
`subject_digest`	path	yes	Subject Digest
`predicate_type`	query	no	Optional filter for fetching attestations with a given predicate type.

Responses

Status	Description	Has JSON body
200	Response	yes
201	Response	yes
204	Response	no
404	Resource not found	yes

List followers of a user

GET /users/{username}/followers

Lists the people following the specified user.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

List the people a user follows

GET /users/{username}/following

Lists the people who the specified user follows.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

Check if a user follows another user

GET /users/{username}/following/{target_user}

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`target_user`	path	yes

Responses

Status	Description	Has JSON body
204	if the user follows the target user	no
404	if the user does not follow the target user	no

List GPG keys for a user

GET /users/{username}/gpg_keys

Lists the GPG keys for a user. This information is accessible by anyone.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

Get contextual information for a user

GET /users/{username}/hovercard

Provides hovercard information. You can find out more about someone in relation to their pull requests, issues, repositories, and organizations.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`subject_type`	query	no	Identifies which additional information you'd like to receive about the person's hovercard. Can be `organization`, `repository`, `issue`, `pull_request`. Required when using `subject_id`.
`subject_id`	query	no	Uses the ID for the `subject_type` you specified. Required when using `subject_type`.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes

List public keys for a user

GET /users/{username}/keys

Lists the _verified_ public SSH keys for a user. This is accessible by anyone.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

List social accounts for a user

GET /users/{username}/social_accounts

Lists social media accounts for a user. This endpoint is accessible by anyone.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

List SSH signing keys for a user

GET /users/{username}/ssh_signing_keys

Lists the SSH signing keys for a user. This operation is accessible by anyone.

Parameters

Name	In	Required	Description
`username`	path	yes	The handle for the GitHub user account.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes