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.0.3
info:
version: 1.1.4
title: GitHub Application About Users API
description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App
installations.'
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
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
tags:
- name: Users
paths:
/users/{username}/events/orgs/{org}:
get:
summary: GitHub List Organization Events for the Authenticated User
description: The GitHub Events API endpoint `/users/{username}/events/orgs/{org}` using the GET method retrieves a list of events for the authenticated user within a specific organization. This endpoint allows developers to access activity data related to a particular organization that the authenticated user is associated with, providing visibility into organization-level events and actions. The API returns event data in a paginated format, showing activities such as repository changes, issue updates, pull requests, and other collaborative actions performed within the specified organization context. Authentication is required to access this endpoint, and the results are filtered to show only events relevant to both the specified username and organization that the authenticated user has permission to view.
tags:
- Users
operationId: listOrganizationEventsForTheAuthenticatedUser
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/activity/events#list-organization-events-for-the-authenticated-user
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/event'
examples:
default:
$ref: '#/components/examples/user-org-events-items'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: activity
subcategory: events
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/{username}/events/public:
get:
summary: GitHub List Public Events for User
description: The List Public Events For A User operation retrieves a paginated list of public events performed by a specified GitHub user. This GET endpoint accepts a username as a path parameter and returns events such as repository pushes, issue comments, pull requests, and other public activities associated with that user's account. The response includes event metadata like timestamps, event types, and related repository information, making it useful for tracking user contributions and activity across GitHub's public repositories. This endpoint supports pagination parameters and requires no authentication for accessing public event data, though authenticated requests have higher rate limits.
tags:
- Users
operationId: listPublicEventsForUser
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/activity/events#list-public-events-for-a-user
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/event'
examples:
default:
$ref: '#/components/examples/user-public-events-items'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: activity
subcategory: events
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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
/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
/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
/repos/{owner}/{repo}/issues/{issue_number}/assignees/{assignee}:
get:
summary: GitHub Check if User Can Be Assigned to Issue
description: 'Checks if a user has permission to be assigned to a specific issue.
If the `assignee` can be assigned to this issue, a `204` status code with no content is returned.
Otherwise a `404` status code is returned.'
tags:
- Users
operationId: checkIfUserCanBeAssignedToIssue
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/issues/assignees#check-if-a-user-can-be-assigned-to-a-issue
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/issue-number'
- name: assignee
in: path
required: true
schema:
type: string
example: example_value
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response if `assignee` can be assigned to `issue_number`
'404':
description: Response if `assignee` can not be assigned to `issue_number`
content:
application/json:
schema:
$ref: '#/components/schemas/basic-error'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: assignees
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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
/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
example: therealomarj
nullable: true
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
/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
/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
/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
/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
/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
# --- truncated at 32 KB (1246 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-users-api-openapi.yml