The GitHub Users API (part of the REST API) lets applications read and, for the authenticated account, manage user-related data on GitHub. It can fetch public profiles for any user or the authenticated users private profile details, list a users public repositories and organizations, and view activity like followers and following.
openapi: 3.2.0
info:
title: Github Users API
version: 1.1.4
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
description: 'Operations tagged Users across 11 of this provider''s published API definitions: github-installation-openapi.yml, github-notifications-openapi.yml, github-openapi.yml, github-organizations-openapi.yml, github-projects-openapi.yml, github-repo-branches-api-openapi.yml, github-repo-collaborators-api-openapi.yml, github-repo-issues-api-openapi.yml, github-repo-tags-api-openapi.yml, github-scim-openapi.yml, github-teams-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
- url: '{protocol}://{hostname}'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
tags:
- name: Users
paths:
/user/installations:
get:
summary: GitHub List App Installations Accessible to the User Access Token
description: 'Lists installations of your GitHub App that the authenticated user has explicit permission (`:read`, `:write`, or `:admin`) to access.
The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.
You can find the permissions for the installation under the `permissions` key.'
tags:
- Users
operationId: listAppInstallationsAccessibleToTheUserAccessToken
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/installations#list-app-installations-accessible-to-the-user-access-token
parameters:
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: You can find the permissions for the installation under the `permissions` key.
content:
application/json:
schema:
type: object
required:
- total_count
- installations
properties:
total_count:
type: integer
installations:
type: array
items:
$ref: '#/components/schemas/installation'
examples:
default:
$ref: '#/components/examples/base-installation-for-auth-user-paginated'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: apps
subcategory: installations
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/user/installations/{installation_id}/repositories:
get:
summary: GitHub List Repositories Accessible to the User Access Token
description: 'List repositories that the authenticated user has explicit permission (`:read`, `:write`, or `:admin`) to access for an installation.
The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.
The access the user has to each repository is included in the hash under the `permissions` key.'
tags:
- Users
operationId: listRepositoriesAccessibleToTheUserAccessToken
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/installations#list-repositories-accessible-to-the-user-access-token
parameters:
- $ref: '#/components/parameters/installation-id'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: The access the user has to each repository is included in the hash under the `permissions` key.
content:
application/json:
schema:
type: object
required:
- total_count
- repositories
properties:
total_count:
type: integer
repository_selection:
type: string
repositories:
type: array
items:
$ref: '#/components/schemas/repository'
examples:
default:
$ref: '#/components/examples/repository-paginated'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: apps
subcategory: installations
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/users/{username}/installation:
get:
summary: GitHub Get User Installation for the Authenticated App
description: 'Enables an authenticated GitHub App to find the user’s installation information.
You must use a [JWT](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.'
tags:
- Users
operationId: getuserInstallationForTheAuthenticatedApp
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/apps#get-a-user-installation-for-the-authenticated-app
parameters:
- $ref: '#/components/parameters/username'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/installation'
examples:
default:
$ref: '#/components/examples/installation'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: apps
subcategory: apps
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/notifications/threads/{thread_id}/subscription:
get:
summary: GitHub Get Thread Subscription for the Authenticated User
description: 'This checks to see if the current user is subscribed to a thread. You can also [get a repository subscription](https://docs.github.com/enterprise-server@3.9/rest/activity/watching#get-a-repository-subscription).
Note that subscriptions are only generated if a user is participating in a conversation--for example, they''ve replied to the thread, were **@mentioned**, or manually subscribe to a thread.'
tags:
- Users
operationId: getThreadSubscriptionForTheAuthenticatedUser
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/activity/notifications#get-a-thread-subscription-for-the-authenticated-user
parameters:
- $ref: '#/components/parameters/thread-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/thread-subscription'
examples:
default:
$ref: '#/components/examples/thread-subscription'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: activity
subcategory: notifications
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/user:
get:
summary: GitHub Get the Authenticated User
description: OAuth app tokens and personal access tokens (classic) need the `user` scope in order for the response to include private profile information.
tags:
- Users
operationId: users/get-authenticated
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/users#get-the-authenticated-user
parameters: []
responses:
'200':
description: Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/private-user'
- $ref: '#/components/schemas/public-user'
examples:
response-with-public-and-private-profile-information:
$ref: '#/components/examples/private-user-response-with-public-and-private-profile-information'
response-with-public-profile-information:
$ref: '#/components/examples/private-user-response-with-public-profile-information'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: users
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update the Authenticated User
description: '**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.'
tags:
- Users
operationId: users/update-authenticated
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/users#update-the-authenticated-user
parameters: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
name:
description: The new name of the user.
type: string
example: Omar Jahandar
email:
description: The publicly visible email address of the user.
type: string
example: omar@example.com
blog:
description: The new blog URL of the user.
type: string
example: blog.example.com
twitter_username:
description: The new Twitter username of the user.
type:
- string
- 'null'
example: therealomarj
company:
description: The new company of the user.
type: string
example: Acme corporation
location:
description: The new location of the user.
type: string
example: Berlin, Germany
hireable:
description: The new hiring availability of the user.
type: boolean
bio:
description: The new short biography of the user.
type: string
examples:
default:
summary: Example of updating blog and name
value:
blog: https://github.com/blog
name: monalisa octocat
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/private-user'
examples:
default:
$ref: '#/components/examples/private-user'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: users
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/user/emails:
get:
summary: GitHub List Email Addresses for the Authenticated User
description: 'Lists all of your email addresses, and specifies which one is visible
to the public.
OAuth app tokens and personal access tokens (classic) need the `user:email` scope to use this endpoint.'
tags:
- Users
operationId: users/list-emails-for-authenticated-user
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/emails#list-email-addresses-for-the-authenticated-user
parameters:
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/email'
examples:
default:
$ref: '#/components/examples/email-items-2'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: emails
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Add an Email Address for the Authenticated User
description: OAuth app tokens and personal access tokens (classic) need the `user` scope to use this endpoint.
tags:
- Users
operationId: users/add-email-for-authenticated-user
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/emails#add-an-email-address-for-the-authenticated-user
parameters: []
requestBody:
required: false
content:
application/json:
schema:
oneOf:
- type: object
properties:
emails:
description: Adds one or more email addresses to your GitHub account. Must contain at least one email address. **Note:** Alternatively, you can pass a single email address or an `array` of emails addresses directly, but we recommend that you pass an object using the `emails` key.
type: array
items:
type: string
example: username@example.com
minItems: 1
example: []
required:
- emails
example:
emails:
- octocat@github.com
- mona@github.com
- type: array
items:
type: string
example: username@example.com
minItems: 1
- type: string
examples:
default:
summary: Example adding multiple email addresses
value:
emails:
- octocat@github.com
- mona@github.com
- octocat@octocat.org
responses:
'201':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/email'
examples:
default:
$ref: '#/components/examples/email-items'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: emails
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete an Email Address for the Authenticated User
description: OAuth app tokens and personal access tokens (classic) need the `user` scope to use this endpoint.
tags:
- Users
operationId: users/delete-email-for-authenticated-user
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/emails#delete-an-email-address-for-the-authenticated-user
parameters: []
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
description: Deletes one or more email addresses from your GitHub account. Must contain at least one email address. **Note:** Alternatively, you can pass a single email address or an `array` of emails addresses directly, but we recommend that you pass an object using the `emails` key.
properties:
emails:
description: Email addresses associated with the GitHub user account.
type: array
items:
type: string
example: username@example.com
minItems: 1
example:
emails:
- octocat@github.com
- mona@github.com
required:
- emails
- type: array
items:
type: string
example: username@example.com
minItems: 1
- type: string
examples:
default:
summary: Example deleting multiple email accounts
value:
emails:
- octocat@github.com
- mona@github.com
responses:
'204':
description: Response
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: emails
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/user/followers:
get:
summary: GitHub List Followers of the Authenticated User
description: Lists the people following the authenticated user.
tags:
- Users
operationId: users/list-followers-for-authenticated-user
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/followers#list-followers-of-the-authenticated-user
parameters:
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: followers
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/user/following:
get:
summary: GitHub List the People the Authenticated User Follows
description: Lists the people who the authenticated user follows.
tags:
- Users
operationId: users/list-followed-by-authenticated-user
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/followers#list-the-people-the-authenticated-user-follows
parameters:
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: followers
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/user/following/{username}:
get:
summary: GitHub Check if a Person is Followed by the Authenticated User
description: ''
tags:
- Users
operationId: users/check-person-is-followed-by-authenticated
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/followers#check-if-a-person-is-followed-by-the-authenticated-user
parameters:
- $ref: '#/components/parameters/username'
responses:
'204':
description: if the person is followed by the authenticated user
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
description: if the person is not followed by the authenticated user
content:
application/json:
schema:
$ref: '#/components/schemas/basic-error'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: followers
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Follow a User
description: 'Note that you''ll need to set `Content-Length` to zero when calling out to this endpoint. For more information, see "[HTTP verbs](https://docs.github.com/enterprise-server@3.9/rest/guides/getting-started-with-the-rest-api#http-method)."
OAuth app tokens and personal access tokens (classic) need the `user:follow` scope to use this endpoint.'
tags:
- Users
operationId: users/follow
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/followers#follow-a-user
parameters:
- $ref: '#/components/parameters/username'
responses:
'204':
description: Response
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: followers
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Unfollow a User
description: OAuth app tokens and personal access tokens (classic) need the `user:follow` scope to use this endpoint.
tags:
- Users
operationId: users/unfollow
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/followers#unfollow-a-user
parameters:
- $ref: '#/components/parameters/username'
responses:
'204':
description: Response
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: followers
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
/user/gpg_keys:
get:
summary: GitHub List GPG Keys for the Authenticated User
description: 'Lists the current user''s GPG keys.
OAuth app tokens and personal access tokens (classic) need the `read:gpg_key` scope to use this endpoint.'
tags:
- Users
operationId: users/list-gpg-keys-for-authenticated-user
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/gpg-keys#list-gpg-keys-for-the-authenticated-user
parameters:
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/gpg-key'
examples:
default:
$ref: '#/components/examples/gpg-key-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: users
subcategory: gpg-keys
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create a GPG Key for the Authenticated User
description: 'Adds a GPG key to the authenticated user''s GitHub account.
OAuth app tokens and personal access tokens (classic) need the `write:gpg_key` scope to use this endpoint.'
operationId: users/create-gpg-key-for-authenticated-user
tags:
- Users
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/users/gpg-keys#create-a-gpg-key-for-the-authenticated-user
parameters: []
requestBody:
required: true
content:
application/json:
schema:
properties:
name:
description: A descriptive name for the new key.
type: string
armored_public_key:
description: A GPG key in ASCII-armored format.
type: string
type: object
required:
- armored_public_key
examples:
default:
value:
name: Octocat's GPG Key
armored_public_key: '--BEGIN PGP PUBLIC KEY BLOCK--
Version: GnuPG v1
mQINBFnZ2ZIBEADQ2Z7Z7
--END PGP PUBLIC KEY BLOCK--'
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/gpg-key'
examples:
default:
$ref: '#/components/examples/gpg-key'
'304':
$ref: '#/components/respons
# --- truncated at 32 KB (338 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-users-api-openapi.yml