Team Discussions

List discussions
Get a discussion
Create a discussion
Update a discussion
Delete a discussion
List discussions (Legacy)
Get a single discussion (Legacy)
Create a discussion (Legacy)
Edit a discussion (Legacy)
Delete a discussion (Legacy)

The team discussions API allows you to get, create, edit, and delete discussion posts on a team's page. You can use team discussions to have conversations that are not specific to a repository or project. Any member of the team's organization can create and read public discussion posts. For more details, see "About team discussions." To learn more about commenting on a discussion post, see the team discussion comments API. This API is only available to authenticated members of the team's organization.

List discussions

Note: The reactions API is available for developers to preview. The url can be used to construct the API location for listing and creating reactions. See the blog post for full details. To receive the reactions object in the response for this endpoint you must provide a custom media type in the Accept header:

application/vnd.github.squirrel-girl-preview

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support or GitHub Premium Support.

List all discussions on a team's page. OAuth access tokens require the read:discussion scope.

Note: You can also specify a team by org_id and team_id using the route GET /organizations/:org_id/team/:team_id/discussions.

GET /orgs/:org/teams/:team_slug/discussions

Parameters

Name	Type	Description
`direction`	`string`	Sorts the discussion comments by the date they were created. To return the oldest comments first, set to `asc`. Can be one of `asc` or `desc`. Default: `desc`

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

[
  {
    "author": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "body": "Hi! This is an area for us to collaborate as a team.",
    "body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
    "body_version": "0d495416a700fb06133c612575d92bfb",
    "comments_count": 0,
    "comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
    "created_at": "2018-01-25T18:56:31Z",
    "last_edited_at": null,
    "html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
    "node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
    "number": 1,
    "pinned": false,
    "private": false,
    "team_url": "https://api.github.com/teams/2343027",
    "title": "Our first team post",
    "updated_at": "2018-01-25T18:56:31Z",
    "url": "https://api.github.com/teams/2343027/discussions/1",
    "reactions": {
      "url": "https://api.github.com/teams/2343027/discussions/1/reactions",
      "total_count": 5,
      "+1": 3,
      "-1": 1,
      "laugh": 0,
      "confused": 0,
      "heart": 1,
      "hooray": 0
    }
  }
]

Get a discussion

application/vnd.github.squirrel-girl-preview

Get a specific discussion on a team's page. OAuth access tokens require the read:discussion scope.

Note: You can also specify a team by org_id and team_id using the route GET /organizations/:org_id/team/:team_id/discussions/:discussion_number.

GET /orgs/:org/teams/:team_slug/discussions/:discussion_number

Response

Status: 200 OK

{
  "author": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "body": "Hi! This is an area for us to collaborate as a team.",
  "body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
  "body_version": "0d495416a700fb06133c612575d92bfb",
  "comments_count": 0,
  "comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
  "created_at": "2018-01-25T18:56:31Z",
  "last_edited_at": null,
  "html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
  "node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
  "number": 1,
  "pinned": false,
  "private": false,
  "team_url": "https://api.github.com/teams/2343027",
  "title": "Our first team post",
  "updated_at": "2018-01-25T18:56:31Z",
  "url": "https://api.github.com/teams/2343027/discussions/1",
  "reactions": {
    "url": "https://api.github.com/teams/2343027/discussions/1/reactions",
    "total_count": 5,
    "+1": 3,
    "-1": 1,
    "laugh": 0,
    "confused": 0,
    "heart": 1,
    "hooray": 0
  }
}

Create a discussion

application/vnd.github.squirrel-girl-preview

Creates a new discussion post on a team's page. OAuth access tokens require the write:discussion scope.

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" and "Dealing with abuse rate limits" for details.

Note: You can also specify a team by org_id and team_id using the route POST /organizations/:org_id/team/:team_id/discussions.

POST /orgs/:org/teams/:team_slug/discussions

Parameters

Name	Type	Description
`title`	`string`	Required. The discussion post's title.
`body`	`string`	Required. The discussion post's body text.
`private`	`boolean`	Private posts are only visible to team members, organization owners, and team maintainers. Public posts are visible to all members of the organization. Set to `true` to create a private post. Default: `false`

Example

{
  "title": "Our first team post",
  "body": "Hi! This is an area for us to collaborate as a team."
}

Response

Status: 201 Created

{
  "author": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "body": "Hi! This is an area for us to collaborate as a team.",
  "body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
  "body_version": "0d495416a700fb06133c612575d92bfb",
  "comments_count": 0,
  "comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
  "created_at": "2018-01-25T18:56:31Z",
  "last_edited_at": null,
  "html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
  "node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
  "number": 1,
  "pinned": false,
  "private": false,
  "team_url": "https://api.github.com/teams/2343027",
  "title": "Our first team post",
  "updated_at": "2018-01-25T18:56:31Z",
  "url": "https://api.github.com/teams/2343027/discussions/1",
  "reactions": {
    "url": "https://api.github.com/teams/2343027/discussions/1/reactions",
    "total_count": 5,
    "+1": 3,
    "-1": 1,
    "laugh": 0,
    "confused": 0,
    "heart": 1,
    "hooray": 0
  }
}

Update a discussion

application/vnd.github.squirrel-girl-preview

Edits the title and body text of a discussion post. Only the parameters you provide are updated. OAuth access tokens require the write:discussion scope.

Note: You can also specify a team by org_id and team_id using the route PATCH /organizations/:org_id/team/:team_id/discussions/:discussion_number.

PATCH /orgs/:org/teams/:team_slug/discussions/:discussion_number

Parameters

Name	Type	Description
`title`	`string`	The discussion post's title.
`body`	`string`	The discussion post's body text.

Example

{
  "title": "Welcome to our first team post"
}

Response

Status: 200 OK

{
  "author": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "body": "Hi! This is an area for us to collaborate as a team.",
  "body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
  "body_version": "0d495416a700fb06133c612575d92bfb",
  "comments_count": 1,
  "comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
  "created_at": "2018-01-25T18:56:31Z",
  "last_edited_at": "2018-01-26T18:22:20Z",
  "html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
  "node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
  "number": 1,
  "pinned": false,
  "private": false,
  "team_url": "https://api.github.com/teams/2343027",
  "title": "Welcome to our first team post",
  "updated_at": "2018-01-26T18:22:20Z",
  "url": "https://api.github.com/teams/2343027/discussions/1",
  "reactions": {
    "url": "https://api.github.com/teams/2343027/discussions/1/reactions",
    "total_count": 5,
    "+1": 3,
    "-1": 1,
    "laugh": 0,
    "confused": 0,
    "heart": 1,
    "hooray": 0
  }
}

Delete a discussion

Delete a discussion from a team's page. OAuth access tokens require the write:discussion scope.

Note: You can also specify a team by org_id and team_id using the route DELETE /organizations/:org_id/team/:team_id/discussions/:discussion_number.

DELETE /orgs/:org/teams/:team_slug/discussions/:discussion_number

Response

Status: 204 No Content

List discussions (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new List discussions endpoint.

application/vnd.github.squirrel-girl-preview

List all discussions on a team's page. OAuth access tokens require the read:discussion scope.

GET /teams/:team_id/discussions

Parameters

Name	Type	Description
`direction`	`string`	Sorts the discussion comments by the date they were created. To return the oldest comments first, set to `asc`. Can be one of `asc` or `desc`. Default: `desc`

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

[
  {
    "author": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "body": "Hi! This is an area for us to collaborate as a team.",
    "body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
    "body_version": "0d495416a700fb06133c612575d92bfb",
    "comments_count": 0,
    "comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
    "created_at": "2018-01-25T18:56:31Z",
    "last_edited_at": null,
    "html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
    "node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
    "number": 1,
    "pinned": false,
    "private": false,
    "team_url": "https://api.github.com/teams/2343027",
    "title": "Our first team post",
    "updated_at": "2018-01-25T18:56:31Z",
    "url": "https://api.github.com/teams/2343027/discussions/1",
    "reactions": {
      "url": "https://api.github.com/teams/2343027/discussions/1/reactions",
      "total_count": 5,
      "+1": 3,
      "-1": 1,
      "laugh": 0,
      "confused": 0,
      "heart": 1,
      "hooray": 0
    }
  }
]

Get a single discussion (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new Get a discussion endpoint.

application/vnd.github.squirrel-girl-preview

Get a specific discussion on a team's page. OAuth access tokens require the read:discussion scope.

GET /teams/:team_id/discussions/:discussion_number

Response

Status: 200 OK

{
  "author": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "body": "Hi! This is an area for us to collaborate as a team.",
  "body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
  "body_version": "0d495416a700fb06133c612575d92bfb",
  "comments_count": 0,
  "comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
  "created_at": "2018-01-25T18:56:31Z",
  "last_edited_at": null,
  "html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
  "node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
  "number": 1,
  "pinned": false,
  "private": false,
  "team_url": "https://api.github.com/teams/2343027",
  "title": "Our first team post",
  "updated_at": "2018-01-25T18:56:31Z",
  "url": "https://api.github.com/teams/2343027/discussions/1",
  "reactions": {
    "url": "https://api.github.com/teams/2343027/discussions/1/reactions",
    "total_count": 5,
    "+1": 3,
    "-1": 1,
    "laugh": 0,
    "confused": 0,
    "heart": 1,
    "hooray": 0
  }
}

Create a discussion (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new Create a discussion endpoint.

application/vnd.github.squirrel-girl-preview

Creates a new discussion post on a team's page. OAuth access tokens require the write:discussion scope.

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" and "Dealing with abuse rate limits" for details.

POST /teams/:team_id/discussions

Parameters

Name	Type	Description
`title`	`string`	Required. The discussion post's title.
`body`	`string`	Required. The discussion post's body text.
`private`	`boolean`	Private posts are only visible to team members, organization owners, and team maintainers. Public posts are visible to all members of the organization. Set to `true` to create a private post. Default: `false`

Example

{
  "title": "Our first team post",
  "body": "Hi! This is an area for us to collaborate as a team."
}

Response

Status: 201 Created

{
  "author": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "body": "Hi! This is an area for us to collaborate as a team.",
  "body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
  "body_version": "0d495416a700fb06133c612575d92bfb",
  "comments_count": 0,
  "comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
  "created_at": "2018-01-25T18:56:31Z",
  "last_edited_at": null,
  "html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
  "node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
  "number": 1,
  "pinned": false,
  "private": false,
  "team_url": "https://api.github.com/teams/2343027",
  "title": "Our first team post",
  "updated_at": "2018-01-25T18:56:31Z",
  "url": "https://api.github.com/teams/2343027/discussions/1",
  "reactions": {
    "url": "https://api.github.com/teams/2343027/discussions/1/reactions",
    "total_count": 5,
    "+1": 3,
    "-1": 1,
    "laugh": 0,
    "confused": 0,
    "heart": 1,
    "hooray": 0
  }
}

Edit a discussion (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new Update a discussion endpoint.

application/vnd.github.squirrel-girl-preview

Edits the title and body text of a discussion post. Only the parameters you provide are updated. OAuth access tokens require the write:discussion scope.

PATCH /teams/:team_id/discussions/:discussion_number

Parameters

Name	Type	Description
`title`	`string`	The discussion post's title.
`body`	`string`	The discussion post's body text.

Example

{
  "title": "Welcome to our first team post"
}

Response

Status: 200 OK

{
  "author": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "body": "Hi! This is an area for us to collaborate as a team.",
  "body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
  "body_version": "0d495416a700fb06133c612575d92bfb",
  "comments_count": 1,
  "comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
  "created_at": "2018-01-25T18:56:31Z",
  "last_edited_at": "2018-01-26T18:22:20Z",
  "html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
  "node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
  "number": 1,
  "pinned": false,
  "private": false,
  "team_url": "https://api.github.com/teams/2343027",
  "title": "Welcome to our first team post",
  "updated_at": "2018-01-26T18:22:20Z",
  "url": "https://api.github.com/teams/2343027/discussions/1",
  "reactions": {
    "url": "https://api.github.com/teams/2343027/discussions/1/reactions",
    "total_count": 5,
    "+1": 3,
    "-1": 1,
    "laugh": 0,
    "confused": 0,
    "heart": 1,
    "hooray": 0
  }
}

Delete a discussion (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new Delete a discussion endpoint.

Delete a discussion from a team's page. OAuth access tokens require the write:discussion scope.

DELETE /teams/:team_id/discussions/:discussion_number

Response

Status: 204 No Content