GitHub Public API Limitations

[setchy]

GitHub Public API Limitations

This issue collates all of the feature gaps within the public GitHub REST API and GitHub GraphQL API

Note

See GitHub Changelog for new feature announcements
See GitHub Public Roadmap for planned upcoming features

Important

Filter issues by github-api-limitation to see full backlog

Authentication Methods

• /notifications does not support fine-grained personal access tokens tokens Add support for fine-grained personal access token auth #1492
• /notifications does not support GitHub App authorization permissions https://github.com/apps/gitify-experimental

GitHub REST API - Documentation

• List Notifications endpoint /notifications
  • Filtering capabilities
    • No query parameter to filter notifications by inbox
    • No query parameter to filter notifications by saved
    • No query parameter to filter notifications by done
  • Response schema
    • No attribute in response indicating if a notification is done, saved or in the inbox.
    • When fetching ?all=true, both read and done notifications are returned with the same response shape. There is no indicator to differentiate if the notification thread is read and not done or read and done, which causes challenges with notification hover interaction button logic.
    • Notifications of subject.type CheckSuite, RepositoryInvitation or WorkflowRun always have null
      for subject.url and subject.latest_comment_url
    • Notifications of subject.type Discussion return
      for subject.url / subject.latest_comment_url which doesn't point to the latest comment. We have had to implement a fix to find these ourselves. See refactor: remove discussions html url workaround #1583
  • Private repositories Notifications show in UI but not via this API
• Notification
  • No endpoint to mark notification as unread (can only mark a notification as read)
  • No endpoint to find CheckSuite of WorkflowRun information by notification_id
  • No endpoint to save/unsave a notification
• Authentication
  • No support for fine-grained tokens Add support for fine-grained personal access token auth #1492

GitHub GraphQL API - Documentation

• No query to fetch user notifications
• No query to find CheckSuite of WorkflowRun information by notification_id
• No query to find Release information by release_id (only by tag)

[0xdevalias]

While it's been a while since I was looking at it, this thread for adding support to view notifications to the gh CLI might have some pointers towards API workarounds, eg:

• Ability to read notifications cli/cli#659 (comment)

  • IIRC you cannot mark notifications as Done, just Read

  • A little light reverse engineering seems to show that the webpage makes a call to /notifications/beta/archive when I click the button

• Ability to read notifications cli/cli#659 (comment)

  • Seems like the Mobile app is using some graphQL API endpoints behind a feature flag

  • POST /graphql HTTP/2
    Host: api.github.com
    Content-Type: application/json
    Graphql-Features: merge_queue,private_profile_setting,project_next_field_configuration,issues_close_state,project_next_recent_connection,file_level_commenting,issue_types,sub_issues
    Accept: application/vnd.github.merge-info-preview+json,application/vnd.github.shadow-cat-preview+json,application/vnd.github.echo-preview+json,application/vnd.github.starfox-preview+json,application/vnd.github.doctor-strange-preview+json
    Apollographql-Client-Version: 1.192.0-152022212
    Authorization: Bearer REDACTED
    Accept-Encoding: gzip, deflate, br
    Accept-Language: en-GB;q=1.0, en-AU;q=0.9, ja-AU;q=0.8, fa-AU;q=0.7
    Content-Length: 4030
    User-Agent: GitHub/1.192.0 (com.github.stormbreaker.prod; build:152022212; iOS 18.2.1; iPhone15,3)
    X-Apollo-Operation-Type: query
    Apollographql-Client-Name: com.github.stormbreaker.prod-apollo-ios
    X-Apollo-Operation-Name: Inbox
    
    {
        "operationName": "Inbox",
        "query": "query Inbox($first: Int!, $after: String, $filterBy: NotificationThreadFilters, $query: String, $avatarSize: Int!) { viewer { __typename id ...WebNotificationsEnabledFragment notificationThreads( first: $first after: $after filterBy: $filterBy query: $query ) { __typename pageInfo { __typename hasNextPage endCursor } totalCount nodes { __typename ...NotificationThreadCommonFieldsFragment url subject { __typename ... on CheckSuite { ...InboxSubjectCheckSuiteFieldsFragment } ... on WorkflowRun { ...InboxSubjectWorkflowRunFieldsFragment } ... on Commit { ...InboxSubjectCommitFieldsFragment } ... on Gist { ...InboxSubjectGistFieldsFragment } ... on TeamDiscussion { ...InboxSubjectTeamDiscussionFieldsFragment } ... on Issue { ...InboxSubjectIssueFieldsFragment } ... on PullRequest { ...InboxSubjectPullRequestFieldsFragment } ... on Release { ...InboxSubjectReleaseFieldsFragment } ... on RepositoryVulnerabilityAlert { ...InboxSubjectRepositoryVulnerabilityAlertFieldsFragment } ... on RepositoryAdvisory { ...InboxSubjectRepositoryAdvisoryFieldsFragment } ...InboxSubjectDiscussionFieldsFragment ... on RepositoryDependabotAlertsThread { ...InboxSubjectRepositoryDependabotAlertsThreadFieldsFragment } ... on SecurityAdvisory { ...InboxSubjectSecurityAdvisoryFieldsFragment } } } } } }\nfragment AvatarFragment on Actor { __typename avatarUrl(size: $avatarSize) }\nfragment InboxSubjectCheckSuiteFieldsFragment on CheckSuite { __typename id url conclusion status }\nfragment InboxSubjectCommitFieldsFragment on Commit { __typename id abbreviatedOid url repository { __typename id owner { __typename id login } name } }\nfragment InboxSubjectDiscussionFieldsFragment on Discussion { __typename id url number discussionStateReason: stateReason answer { __typename id } category { __typename id isAnswerable } repository { __typename id isOrganizationDiscussionRepository } }\nfragment InboxSubjectGistFieldsFragment on Gist { __typename url id }\nfragment InboxSubjectIssueFieldsFragment on Issue { __typename id number issueState: state stateReason issueHtmlTitle: titleHTML url }\nfragment InboxSubjectPullRequestFieldsFragment on PullRequest { __typename id number pullRequestHtmlTitle: titleHTML url ...PullRequestStateIcon }\nfragment InboxSubjectReleaseFieldsFragment on Release { __typename id tagName url }\nfragment InboxSubjectRepositoryAdvisoryFieldsFragment on RepositoryAdvisory { __typename id url }\nfragment InboxSubjectRepositoryDependabotAlertsThreadFieldsFragment on RepositoryDependabotAlertsThread { __typename id notificationsPermalink }\nfragment InboxSubjectRepositoryVulnerabilityAlertFieldsFragment on RepositoryVulnerabilityAlert { __typename id permalink }\nfragment InboxSubjectSecurityAdvisoryFieldsFragment on SecurityAdvisory { __typename id ghsaId notificationsPermalink }\nfragment InboxSubjectTeamDiscussionFieldsFragment on TeamDiscussion { __typename url id }\nfragment InboxSubjectWorkflowRunFieldsFragment on WorkflowRun { __typename id url runNumber workflow { __typename id name } checkSuite { __typename id } }\nfragment ListSubscribableFragment on Subscribable { __typename id viewerSubscription viewerCanSubscribe }\nfragment NotificationThreadCommonFieldsFragment on NotificationThread { __typename id threadType title isUnread unreadItemsCount lastUpdatedAt subscriptionStatus summaryItemAuthor { __typename id ...AvatarFragment } summaryItemBody isArchived isSaved reason list { __typename ...ListSubscribableFragment ... on Repository { id owner { __typename id login } name } ... on User { id login userName: name } ... on Team { id organization { __typename id login } slug } ... on Organization { id login } } }\nfragment PullRequestStateIcon on PullRequest { __typename pullRequestState: state isDraft mergeQueueEntry { __typename id position } }\nfragment WebNotificationsEnabledFragment on User { __typename notificationSettings { __typename getsParticipatingWeb getsWatchingWeb } }",
        "variables":
        {
            "avatarSize": 48,
            "first": 30,
            "query": ""
        }
    }

  • And then if I click on a filter tab in the iOS app like 'unread' it changes query to is:unread; saved is is:saved, done is is:done, etc
  • Mark notification as 'undone':

    • POST /graphql HTTP/1.1
      Host: api.github.com
      GraphQL-Features: merge_queue,private_profile_setting,project_next_field_configuration,issues_close_state,project_next_recent_connection,file_level_commenting,issue_types,sub_issues
      Authorization: Bearer gho_REDACTED
      Accept: multipart/mixed;deferSpec=20220824,application/graphql-response+json,application/json,application/vnd.github.merge-info-preview+json,application/vnd.github.shadow-cat-preview+json,application/vnd.github.echo-preview+json,application/vnd.github.starfox-preview+json,application/vnd.github.doctor-strange-preview+json
      apollographql-client-version: 1.222.0-170680083
      Accept-Language: en-GB;q=1.0, en-AU;q=0.9, ja-AU;q=0.8, fa-AU;q=0.7
      Accept-Encoding: br;q=1.0, gzip;q=0.9, deflate;q=0.8
      Content-Type: application/json
      Content-Length: 265
      User-Agent: GitHub/1.222.0 (com.github.stormbreaker.prod; build:170680083; iOS 18.6.0; iPhone15,3)
      X-APOLLO-OPERATION-TYPE: mutation
      apollographql-client-name: com.github.stormbreaker.prod-apollo-ios
      Connection: keep-alive
      X-APOLLO-OPERATION-NAME: MarkNotificationAsUndone
      
      {
        "operationName": "MarkNotificationAsUndone",
        "query": "mutation MarkNotificationAsUndone($notificationId: ID!) { markNotificationAsUndone(input: { id: $notificationId }) { __typename success } }",
        "variables": {
          "notificationId": "NT_kwDOAAuA47E4ODcxMjU0MzkzOjc1Mzg5MQ"
        }
      }

  • Save/unsave/view saved: feature: save/saved notifications #840 (comment)

Some of the private APIs used on https://github.com/notifications (though likely less useful as they use authenticity_token to prevent CSRF:

• mark as read:
  • POST https://github.com/notifications/beta/mark
  • MIME Type: multipart/form-data

  • ------WebKitFormBoundaryLqH0emMzDeIcrXrh
    Content-Disposition: form-data; name="authenticity_token"
    
    REDACTED
    ------WebKitFormBoundaryLqH0emMzDeIcrXrh
    Content-Disposition: form-data; name="notification_ids[]"
    
    NT_kwDOAAuA47IxODEzREDACTED
    ------WebKitFormBoundaryLqH0emMzDeIcrXrh
    Content-Disposition: form-data; name="notification_ids[]"
    
    NT_kwDOAAuA47IxODM0REDACTED
    ------WebKitFormBoundaryLqH0emMzDeIcrXrh--
    

• mark as unread:
  • POST https://github.com/notifications/beta/unmark
  • MIME Type: multipart/form-data

  • ------WebKitFormBoundaryBWyAgv8M6HPBkTAX
    Content-Disposition: form-data; name="authenticity_token"
    
    REDACTED
    ------WebKitFormBoundaryBWyAgv8M6HPBkTAX
    Content-Disposition: form-data; name="notification_ids[]"
    
    NT_kwDOAAuA47IxODEzREDACTED
    ------WebKitFormBoundaryBWyAgv8M6HPBkTAX
    Content-Disposition: form-data; name="notification_ids[]"
    
    NT_kwDOAAuA47IxODM0REDACTED
    ------WebKitFormBoundaryBWyAgv8M6HPBkTAX--
    

• mark as done / archive:
  • POST https://github.com/notifications/beta/archive
  • MIME Type: multipart/form-data

  • ------WebKitFormBoundary1RpEegHaXAmtMNxM
    Content-Disposition: form-data; name="authenticity_token"
    
    REDACTED
    ------WebKitFormBoundary1RpEegHaXAmtMNxM
    Content-Disposition: form-data; name="notification_ids[]"
    
    NT_kwDOAAuA47IxODEzREDACTED
    ------WebKitFormBoundary1RpEegHaXAmtMNxM
    Content-Disposition: form-data; name="notification_ids[]"
    
    NT_kwDOAAuA47IxODM0REDACTED
    ------WebKitFormBoundary1RpEegHaXAmtMNxM--