Team Discussions

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 team discussions API is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.echo-preview+json

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.

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,
      "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",
    "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

Note: The team discussions API is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.echo-preview+json

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.

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,
    "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",
  "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

Note: The team discussions API is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.echo-preview+json

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.

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

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,
    "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",
  "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

Note: The team discussions API is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.echo-preview+json

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.

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,
    "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",
  "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

Note: The team discussions API is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.echo-preview+json

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.

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