jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity
Files
main
docs/content/graphql/guides/using-the-graphql-api-for-discussions.md
Rachael Sewell 74e6642840 Deprecate GHES 3.11
2025-02-20 11:36:42 -08:00

1097 lines
22 KiB
Markdown
Raw Permalink Blame History

---
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. If `answered` is not specified, both answered and unanswered discussions will be returned.
_Signature:_
```graphql
discussions(
after: String,
before: String,
first: Int,
last: Int,
categoryId: ID = null,
answered: Boolean = null,
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
<details>
<summary>Fields:</summary>
```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
"""
Check if this discussion has been answered
"""
isAnswered: Boolean!
"""
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
}
```
</details>
### DiscussionComment
<details>
<summary>Fields</summary>
```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!
}
```
</details>
### DiscussionCategory
<details>
<summary>Fields</summary>
```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!
}
```
</details>
### PinnedDiscussion
<details>
<summary>Fields:</summary>
```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!
}
```
</details>
#### PinnedDiscussionPattern
<details>
<summary>Values</summary>
```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
}
```
</details>
#### PinnedDiscussionGradient
<details>
<summary>Values</summary>
```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
}
```
</details>
## 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`.
<details>
<summary>Fields</summary>
```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!
}
```
</details>
### RepositoryDiscussionCommentAuthor
Also implemented by the `User` and `Organization` types.
<details>
<summary>Fields</summary>
```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!
}
```
</details>
## 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).
Reference in New Issue View Git Blame Copy Permalink