--- title: Using the GraphQL API for Discussions intro: 'Learn how to use the {% data variables.product.prodname_discussions %} GraphQL API.' versions: fpt: '*' ghes: '*' ghec: '*' shortTitle: Use GraphQL for Discussions --- The {% data variables.product.prodname_discussions %} GraphQL API allows you to get, create, edit, and delete discussion posts. For more information about {% data variables.product.prodname_discussions %}, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). This API is available for authenticated users, {% data variables.product.prodname_oauth_apps %}, and GitHub Apps. Access tokens require the `repo` scope for private repositories and the `public_repo` scope for public repositories. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). ## Fields ### Repository.discussions List the discussions within a repository. If `categoryId` is specified, only results within that category will be returned. {% ifversion answered-fields-for-discussions %}If `answered` is not specified, both answered and unanswered discussions will be returned.{% endif %} _Signature:_ ```graphql discussions( after: String, before: String, first: Int, last: Int, categoryId: ID = null, {%- ifversion answered-fields-for-discussions %} answered: Boolean = null, {%- endif %} orderBy: DiscussionOrder = {field: UPDATED_AT, direction: DESC} ) : Discussion ``` #### DiscussionOrder ```graphql """ Ways in which discussions can be ordered. """ input DiscussionOrder { """ The field by which to order discussions. """ field: DiscussionOrderField! """ The direction in which to order discussions by the specified field. """ direction: OrderDirection! } ``` ```graphql """ Properties by which discussion connections can be ordered. """ enum DiscussionOrderField { """ Order discussions by creation time. """ CREATED_AT """ Order discussions by most recent modification time. """ UPDATED_AT } ``` ### Repository.discussionCategories Return the available discussion categories defined within this repository. Each repository may have up to 25 categories. For more information about discussion categories, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-categories-and-formats-for-discussions). _Signature:_ ```graphql discussionCategories( after: String, before: String, first: Int, last: Int, ) : DiscussionCategoryConnection! ``` ### Repository.discussion Get a discussion. Returns `null` if discussion with the specified ID does not exist. _Signature:_ ```graphql discussion(number: Int!) : Discussion ``` ### Repository.pinnedDiscussions Return discussions pinned to this repository, ordered by pin position. _Signature:_ ```graphql pinnedDiscussions( after: String, before: String, first: Int, last: Int, ) : PinnedDiscussionConnection! ``` ## Objects **Note:** For brevity, connection types are not expanded here. Each connection type mentioned in the schema follows the same pattern as other connections in the GraphQL API. For more information, see [AUTOTITLE](/graphql/guides/introduction-to-graphql#connection). ```graphql query { repository(owner: "github", name: "some-repo") { discussions(first: 10) { # type: DiscussionConnection totalCount # Int! pageInfo { # type: PageInfo (from the public schema) startCursor endCursor hasNextPage hasPreviousPage } edges { # type: DiscussionEdge cursor node { # type: Discussion id } } nodes { # type: Discussion id } } } } ``` ### Discussion
Fields: ```graphql """ A discussion in a repository. """ type Discussion implements Comment & Deletable & Lockable & Node & Reactable & RepositoryNode & Subscribable & Updatable { """ Reason that the conversation was locked. """ activeLockReason: LockReason {%- ifversion answered-fields-for-discussions %} """ Check if this discussion has been answered """ isAnswered: Boolean! {%- endif %} """ The comment chosen as this discussion's answer, if any. """ answer: DiscussionComment """ The time when a user chose this discussion's answer, if answered. """ answerChosenAt: DateTime """ The user who chose this discussion's answer, if answered. """ answerChosenBy: Actor """ The actor who authored the comment. """ author: Actor """ Author's association with the subject of the comment. """ authorAssociation: CommentAuthorAssociation! """ The main text of the discussion post. """ body: String! """ The body rendered to HTML. """ bodyHTML: HTML! """ The body rendered to text. """ bodyText: String! """ The category for this discussion. """ category: DiscussionCategory! """ The replies to the discussion. """ comments( """ Returns the elements in the list that come after the specified cursor. """ after: String """ Returns the elements in the list that come before the specified cursor. """ before: String """ Returns the first _n_ elements from the list. """ first: Int """ Returns the last _n_ elements from the list. """ last: Int ): DiscussionCommentConnection! """ Identifies the date and time when the object was created. """ createdAt: DateTime! """ Check if this comment was created via an email reply. """ createdViaEmail: Boolean! """ Identifies the primary key from the database. """ databaseId: Int """ The actor who edited the comment. """ editor: Actor id: ID! """ Check if this comment was edited and includes an edit with the creation data """ includesCreatedEdit: Boolean! """ The moment the editor made the last edit """ lastEditedAt: DateTime """ `true` if the object is locked """ locked: Boolean! """ The number identifying this discussion within the repository. """ number: Int! """ Identifies when the comment was published at. """ publishedAt: DateTime """ A list of reactions grouped by content left on the subject. """ reactionGroups: [ReactionGroup!] """ A list of Reactions left on the Issue. """ reactions( """ Returns the elements in the list that come after the specified cursor. """ after: String """ Returns the elements in the list that come before the specified cursor. """ before: String """ Allows filtering Reactions by emoji. """ content: ReactionContent """ Returns the first _n_ elements from the list. """ first: Int """ Returns the last _n_ elements from the list. """ last: Int """ Allows specifying the order in which reactions are returned. """ orderBy: ReactionOrder ): ReactionConnection! """ The repository associated with this node. """ repository: Repository! """ The path for this discussion. """ resourcePath: URI! """ The title of this discussion. """ title: String! """ Identifies the date and time when the object was last updated. """ updatedAt: DateTime! """ The URL for this discussion. """ url: URI! """ A list of edits to this content. """ userContentEdits( """ Returns the elements in the list that come after the specified cursor. """ after: String """ Returns the elements in the list that come before the specified cursor. """ before: String """ Returns the first _n_ elements from the list. """ first: Int """ Returns the last _n_ elements from the list. """ last: Int ): UserContentEditConnection """ Check if the current viewer can delete this object. """ viewerCanDelete: Boolean! """ Can user react to this subject """ viewerCanReact: Boolean! """ Check if the viewer is able to change their subscription status for the repository. """ viewerCanSubscribe: Boolean! """ Check if the current viewer can update this object. """ viewerCanUpdate: Boolean! """ Did the viewer author this comment. """ viewerDidAuthor: Boolean! """ Identifies if the viewer is watching, not watching, or ignoring the subscribable entity. """ viewerSubscription: SubscriptionState } ```
### DiscussionComment
Fields ```graphql """ A comment on a discussion. """ type DiscussionComment implements Comment & Deletable & Minimizable & Node & Reactable & Updatable & UpdatableComment { """ The actor who authored the comment. """ author: Actor """ Author's association with the subject of the comment. """ authorAssociation: CommentAuthorAssociation! """ The body as Markdown. """ body: String! """ The body rendered to HTML. """ bodyHTML: HTML! """ The body rendered to text. """ bodyText: String! """ Identifies the date and time when the object was created. """ createdAt: DateTime! """ Check if this comment was created via an email reply. """ createdViaEmail: Boolean! """ Identifies the primary key from the database. """ databaseId: Int """ The time when this replied-to comment was deleted """ deletedAt: DateTime """ The discussion this comment was created in """ discussion: Discussion """ The actor who edited the comment. """ editor: Actor id: ID! """ Check if this comment was edited and includes an edit with the creation data """ includesCreatedEdit: Boolean! """ Has this comment been chosen as the answer of its discussion? """ isAnswer: Boolean! """ Returns whether or not a comment has been minimized. """ isMinimized: Boolean! """ The moment the editor made the last edit """ lastEditedAt: DateTime """ Returns why the comment was minimized. """ minimizedReason: String """ Identifies when the comment was published at. """ publishedAt: DateTime """ A list of reactions grouped by content left on the subject. """ reactionGroups: [ReactionGroup!] """ A list of Reactions left on the Issue. """ reactions( """ Returns the elements in the list that come after the specified cursor. """ after: String """ Returns the elements in the list that come before the specified cursor. """ before: String """ Allows filtering Reactions by emoji. """ content: ReactionContent """ Returns the first _n_ elements from the list. """ first: Int """ Returns the last _n_ elements from the list. """ last: Int """ Allows specifying the order in which reactions are returned. """ orderBy: ReactionOrder ): ReactionConnection! """ The threaded replies to this comment. """ replies( """ Returns the elements in the list that come after the specified cursor. """ after: String """ Returns the elements in the list that come before the specified cursor. """ before: String """ Returns the first _n_ elements from the list. """ first: Int """ Returns the last _n_ elements from the list. """ last: Int ): DiscussionCommentConnection! """ The discussion comment this comment is a reply to """ replyTo: DiscussionComment """ The path for this discussion comment. """ resourcePath: URI! """ Identifies the date and time when the object was last updated. """ updatedAt: DateTime! """ The URL for this discussion comment. """ url: URI! """ A list of edits to this content. """ userContentEdits( """ Returns the elements in the list that come after the specified cursor. """ after: String """ Returns the elements in the list that come before the specified cursor. """ before: String """ Returns the first _n_ elements from the list. """ first: Int """ Returns the last _n_ elements from the list. """ last: Int ): UserContentEditConnection """ Check if the current viewer can delete this object. """ viewerCanDelete: Boolean! """ Can the current user mark this comment as an answer? """ viewerCanMarkAsAnswer: Boolean! """ Check if the current viewer can minimize this object. """ viewerCanMinimize: Boolean! """ Can user react to this subject """ viewerCanReact: Boolean! """ Can the current user unmark this comment as an answer? """ viewerCanUnmarkAsAnswer: Boolean! """ Check if the current viewer can update this object. """ viewerCanUpdate: Boolean! """ Reasons why the current viewer can not update this comment. """ viewerCannotUpdateReasons: [CommentCannotUpdateReason!]! """ Did the viewer author this comment. """ viewerDidAuthor: Boolean! } ```
### DiscussionCategory
Fields ```graphql """ A category for discussions in a repository. """ type DiscussionCategory implements Node & RepositoryNode { """ Identifies the date and time when the object was created. """ createdAt: DateTime! """ A description of this category. """ description: String """ An emoji representing this category. """ emoji: String! """ This category's emoji rendered as HTML. """ emojiHTML: HTML! id: ID! """ Whether or not discussions in this category support choosing an answer with the markDiscussionCommentAsAnswer mutation. """ isAnswerable: Boolean! """ The name of this category. """ name: String! """ The repository associated with this node. """ repository: Repository! """ Identifies the date and time when the object was last updated. """ updatedAt: DateTime! } ```
### PinnedDiscussion
Fields: ```graphql """ A Pinned discussion is a discussion pinned to a repository's index page. """ type PinnedDiscussion implements Node & RepositoryNode { """ Identifies the date and time when the object was created. """ createdAt: DateTime! """ Identifies the primary key from the database. """ databaseId: Int """ The discussion that was pinned. """ discussion: Discussion! """ Color stops of the chosen gradient """ gradientStopColors: [String!]! id: ID! """ Background texture pattern """ pattern: PinnedDiscussionPattern! """ The actor that pinned this discussion. """ pinnedBy: Actor! """ Preconfigured background gradient option """ preconfiguredGradient: PinnedDiscussionGradient """ The repository associated with this node. """ repository: Repository! """ Identifies the date and time when the object was last updated. """ updatedAt: DateTime! } ```
#### PinnedDiscussionPattern
Values ```graphql """ Preconfigured background patterns that may be used to style discussions pinned within a repository. """ enum PinnedDiscussionPattern { """ An upward-facing chevron pattern """ CHEVRON_UP """ A hollow dot pattern """ DOT """ A solid dot pattern """ DOT_FILL """ A heart pattern """ HEART_FILL """ A friendly octocat face pattern """ OCTOFACE """ A plus sign pattern """ PLUS } ```
#### PinnedDiscussionGradient
Values ```graphql """ Preconfigured gradients that may be used to style discussions pinned within a repository. """ enum PinnedDiscussionGradient { """ A gradient of blue to mint """ BLUE_MINT """ A gradient of blue to purple """ BLUE_PURPLE """ A gradient of pink to blue """ PINK_BLUE """ A gradient of purple to coral """ PURPLE_CORAL """ A gradient of red to orange """ RED_ORANGE } ```
## Interfaces ### RepositoryDiscussionAuthor Implemented by the `User` and `Organization` types. **Note:** An `Organization` will only have discussions associated with it if it was converted from a `User`.
Fields ```graphql """ Represents an author of discussions in repositories. """ interface RepositoryDiscussionAuthor { """ Discussions this user has started. """ repositoryDiscussions( """ Returns the elements in the list that come after the specified cursor. """ after: String """ Filter discussions to only those that have been answered or not. Defaults to including both answered and unanswered discussions. """ answered: Boolean = null """ Returns the elements in the list that come before the specified cursor. """ before: String """ Returns the first _n_ elements from the list. """ first: Int """ Returns the last _n_ elements from the list. """ last: Int """ Ordering options for discussions returned from the connection. """ orderBy: DiscussionOrder = {field: CREATED_AT, direction: DESC} """ Filter discussions to only those in a specific repository. """ repositoryId: ID ): DiscussionConnection! } ```
### RepositoryDiscussionCommentAuthor Also implemented by the `User` and `Organization` types.
Fields ```graphql """ Represents an author of discussion comments in repositories. """ interface RepositoryDiscussionCommentAuthor { """ Discussion comments this user has authored. """ repositoryDiscussionComments( """ Returns the elements in the list that come after the specified cursor. """ after: String """ Returns the elements in the list that come before the specified cursor. """ before: String """ Returns the first _n_ elements from the list. """ first: Int """ Returns the last _n_ elements from the list. """ last: Int """ Filter discussion comments to only those that were marked as the answer """ onlyAnswers: Boolean = false """ Filter discussion comments to only those in a specific repository. """ repositoryId: ID ): DiscussionCommentConnection! } ```
## Mutations These mutations follow the same implementation pattern that other mutations in the GraphQL API. Each mutation accepts a single argument of an `Input` type, named after the mutation, and returns a `Payload` type containing the fields specified. For example, this is a basic `createDiscussion` mutation that will create a new discussion: ```graphql mutation { # input type: CreateDiscussionInput createDiscussion(input: {repositoryId: "1234", categoryId: "5678", body: "The body", title: "The title"}) { # response type: CreateDiscussionPayload discussion { id } } } ``` ### createDiscussion Input fields: * `body: String!` The body of the new discussion. * `title: String!` The title of the new discussion. * `repositoryId: ID!` The ID of a repository in which to create the discussion. * `categoryId: ID!` The ID of a `DiscussionCategory` within this repository. * `clientMutationId: String` A unique identifier for the client performing the mutation. Return type fields: * `clientMutationId: String` The unique identifier provided as an input. * `discussion: Discussion` The discussion that was created. ### updateDiscussion Input fields: * `discussionId: ID!` The node ID of the discussion to update. * `body: String` The new contents of the discussion body. * `title: String` The new discussion title. * `categoryId: ID` The node ID of a `DiscussionCategory` within the same repository to change this discussion to. * `clientMutationId: String` A unique identifier for the client performing the mutation. Return type fields: * `clientMutationId: String` The unique identifier provided as an input. * `discussion: Discussion` The discussion that was modified. ### deleteDiscussion Input fields: * `id: ID!` The node ID of the discussion to delete. * `clientMutationId: String` A unique identifier for the client performing the mutation. Return type fields: * `clientMutationId: String` The unique identifier provided as an input. * `discussion: Discussion` The discussion that was deleted. ### addDiscussionComment Input fields: * `body: String!` The contents of the comment. * `discussionId: ID!` The node ID of the discussion to comment on. * `replyToId: ID` The node ID of the discussion comment to reply to. If absent, the created comment will be a top-level comment. * `clientMutationId: String` A unique identifier for the client performing the mutation. Return type fields: * `clientMutationId: String` The unique identifier provided as an input. * `comment: DiscussionComment` The discussion comment that was created. ### updateDiscussionComment Input fields: * `body: String!` The new contents of the comment body. * `commentId: ID!` The node ID of the discussion comment to update. * `clientMutationId: String` A unique identifier for the client performing the mutation. Return type fields: * `clientMutationId: String` The unique identifier provided as an input. * `comment: DiscussionComment` The discussion comment that was updated. ### deleteDiscussionComment Input fields: * `id: ID!` The node ID of the discussion comment to delete. * `clientMutationId: String` A unique identifier for the client performing the mutation. Return type fields: * `clientMutationId: String` The unique identifier provided as an input. * `comment: DiscussionComment` The discussion comment that was deleted. ### markDiscussionCommentAsAnswer Input fields: * `id: ID!` The node ID of the discussion comment to mark as an answer. * `clientMutationId: String` A unique identifier for the client performing the mutation. Return type fields: * `clientMutationId: String` The unique identifier provided as an input. * `discussion: Discussion` The discussion that includes the chosen comment. ### unmarkDiscussionCommentAsAnswer Input fields: * `id: ID!` The node ID of the discussion comment to unmark as an answer. * `clientMutationId: String` A unique identifier for the client performing the mutation. Return type fields: * `clientMutationId: String` The unique identifier provided as an input. * `discussion: Discussion` The discussion that includes the unmarked comment. ## Search Discussion may be returned from the top-level `search` field. To search for discussion, specify `type` as `DISCUSSION`. The `SearchResultItemConnection` type has a `discussionCount` field to report the number of returned discussions, and the `Discussion` type is added to the `SearchResultItem` union. For more information, see [AUTOTITLE](/graphql/reference/queries#searchresultitemconnection) and [AUTOTITLE](/search-github/searching-on-github/searching-discussions).