REST API endpoints for Projects (classic) - GitHub Enterprise Cloud Docs

List organization projects

Warning

Closing down notice: Projects (classic) is being deprecated in favor of the new Projects experience. See the changelog for more information.

Fine-grained access tokens for "List organization projects"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Projects" organization permissions (read)

Parameters for "List organization projects"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Query parameters
Name, Type, Description
`state` string Indicates the state of the projects to return. Default: `open` Can be one of: `open`, `closed`, `all`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

HTTP response status codes for "List organization projects"

Status code	Description
`200`	OK
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "List organization projects"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/projects

curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/projects

Response

Status: 200

[ { "owner_url": "https://api.github.com/orgs/octocat", "url": "https://api.github.com/projects/1002605", "html_url": "https://github.com/orgs/api-playground/projects/1", "columns_url": "https://api.github.com/projects/1002605/columns", "id": 1002605, "node_id": "MDc6UHJvamVjdDEwMDI2MDU=", "name": "Organization Roadmap", "body": "High-level roadmap for the upcoming year.", "number": 1, "state": "open", "creator": { "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 }, "created_at": "2011-04-11T20:09:31Z", "updated_at": "2014-03-04T18:58:10Z", "organization_permission": "write", "private": true } ]

Create an organization project

Warning

Closing down notice: Projects (classic) is being deprecated in favor of the new Projects experience. See the changelog for more information.

Fine-grained access tokens for "Create an organization project"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Projects" organization permissions (write)

Parameters for "Create an organization project"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Body parameters
Name, Type, Description
`name` string Required The name of the project.
`body` string The description of the project.

HTTP response status codes for "Create an organization project"

Status code	Description
`201`	Created
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`410`	Gone
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Create an organization project"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/orgs/{org}/projects

curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/projects \ -d '{"name":"Organization Roadmap","body":"High-level roadmap for the upcoming year."}'

Response

Status: 201

{ "owner_url": "https://api.github.com/orgs/octocat", "url": "https://api.github.com/projects/1002605", "html_url": "https://github.com/orgs/api-playground/projects/1", "columns_url": "https://api.github.com/projects/1002605/columns", "id": 1002605, "node_id": "MDc6UHJvamVjdDEwMDI2MDU=", "name": "Organization Roadmap", "body": "High-level roadmap for the upcoming year.", "number": 1, "state": "open", "creator": { "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 }, "created_at": "2011-04-11T20:09:31Z", "updated_at": "2014-03-04T18:58:10Z" }

Get a project

Warning

Closing down notice: Projects (classic) is being deprecated in favor of the new Projects experience. See the changelog for more information.

Fine-grained access tokens for "Get a project"

This endpoint works with the following fine-grained token types:

The fine-grained token must have at least one of the following permission sets:

"Projects" repository permissions (read)
"Projects" organization permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "Get a project"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`project_id` integer Required The unique identifier of the project.

HTTP response status codes for "Get a project"

Status code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication
`403`	Forbidden

Code samples for "Get a project"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/projects/{project_id}

curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/projects/PROJECT_ID

Response

Status: 200

{ "owner_url": "https://api.github.com/repos/api-playground/projects-test", "url": "https://api.github.com/projects/1002604", "html_url": "https://github.com/api-playground/projects-test/projects/1", "columns_url": "https://api.github.com/projects/1002604/columns", "id": 1002604, "node_id": "MDc6UHJvamVjdDEwMDI2MDQ=", "name": "Projects Documentation", "body": "Developer documentation project for the developer site.", "number": 1, "state": "open", "creator": { "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 }, "created_at": "2011-04-10T20:09:31Z", "updated_at": "2014-03-03T18:58:10Z" }

Update a project

Warning

Closing down notice: Projects (classic) is being deprecated in favor of the new Projects experience. See the changelog for more information.

Fine-grained access tokens for "Update a project"

This endpoint works with the following fine-grained token types:

The fine-grained token must have at least one of the following permission sets:

"Projects" repository permissions (write)
"Projects" organization permissions (write)

Parameters for "Update a project"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`project_id` integer Required The unique identifier of the project.

Body parameters
Name, Type, Description
`name` string Name of the project
`body` string or null Body of the project
`state` string State of the project; either 'open' or 'closed'
`organization_permission` string The baseline permission that all organization members have on this project Can be one of: `read`, `write`, `admin`, `none`
`private` boolean Whether or not this project can be seen by everyone.

HTTP response status codes for "Update a project"

Status code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication
`403`	Forbidden
`404`	Not Found if the authenticated user does not have access to the project
`410`	Gone
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Update a project"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

patch/projects/{project_id}

curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/projects/PROJECT_ID \ -d '{"name":"Week One Sprint","state":"open","organization_permission":"write"}'

Response

Status: 200

{ "owner_url": "https://api.github.com/repos/api-playground/projects-test", "url": "https://api.github.com/projects/1002604", "html_url": "https://github.com/api-playground/projects-test/projects/1", "columns_url": "https://api.github.com/projects/1002604/columns", "id": 1002604, "node_id": "MDc6UHJvamVjdDEwMDI2MDQ=", "name": "Projects Documentation", "body": "Developer documentation project for the developer site.", "number": 1, "state": "open", "creator": { "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 }, "created_at": "2011-04-10T20:09:31Z", "updated_at": "2014-03-03T18:58:10Z" }

Delete a project

Warning

Closing down notice: Projects (classic) is being deprecated in favor of the new Projects experience. See the changelog for more information.

Fine-grained access tokens for "Delete a project"

This endpoint works with the following fine-grained token types:

The fine-grained token must have at least one of the following permission sets:

"Projects" repository permissions (write)
"Projects" organization permissions (write)

Parameters for "Delete a project"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`project_id` integer Required The unique identifier of the project.

HTTP response status codes for "Delete a project"

Status code	Description
`204`	Delete Success
`304`	Not modified
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`410`	Gone

Code samples for "Delete a project"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/projects/{project_id}

curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/projects/PROJECT_ID

Delete Success

Status: 204

List repository projects

Warning

Closing down notice: Projects (classic) is being deprecated in favor of the new Projects experience. See the changelog for more information.

Fine-grained access tokens for "List repository projects"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Projects" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "List repository projects"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.

Query parameters
Name, Type, Description
`state` string Indicates the state of the projects to return. Default: `open` Can be one of: `open`, `closed`, `all`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

HTTP response status codes for "List repository projects"

Status code	Description
`200`	OK
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`410`	Gone
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "List repository projects"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/repos/{owner}/{repo}/projects

curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/projects

Response

Status: 200

[ { "owner_url": "https://api.github.com/repos/api-playground/projects-test", "url": "https://api.github.com/projects/1002604", "html_url": "https://github.com/api-playground/projects-test/projects/1", "columns_url": "https://api.github.com/projects/1002604/columns", "id": 1002604, "node_id": "MDc6UHJvamVjdDEwMDI2MDQ=", "name": "Projects Documentation", "body": "Developer documentation project for the developer site.", "number": 1, "state": "open", "creator": { "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 }, "created_at": "2011-04-10T20:09:31Z", "updated_at": "2014-03-03T18:58:10Z" } ]

Create a repository project

Warning

Closing down notice: Projects (classic) is being deprecated in favor of the new Projects experience. See the changelog for more information.

Fine-grained access tokens for "Create a repository project"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Projects" repository permissions (write)

Parameters for "Create a repository project"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.

Body parameters
Name, Type, Description
`name` string Required The name of the project.
`body` string The description of the project.

HTTP response status codes for "Create a repository project"

Status code	Description
`201`	Created
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`410`	Gone
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Create a repository project"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/repos/{owner}/{repo}/projects

curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/projects \ -d '{"name":"Projects Documentation","body":"Developer documentation project for the developer site."}'

Response

Status: 201

{ "owner_url": "https://api.github.com/repos/api-playground/projects-test", "url": "https://api.github.com/projects/1002604", "html_url": "https://github.com/api-playground/projects-test/projects/1", "columns_url": "https://api.github.com/projects/1002604/columns", "id": 1002604, "node_id": "MDc6UHJvamVjdDEwMDI2MDQ=", "name": "Projects Documentation", "body": "Developer documentation project for the developer site.", "number": 1, "state": "open", "creator": { "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 }, "created_at": "2011-04-10T20:09:31Z", "updated_at": "2014-03-03T18:58:10Z" }

Create a user project

Warning

Closing down notice: Projects (classic) is being deprecated in favor of the new Projects experience. See the changelog for more information.

Fine-grained access tokens for "Create a user project"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Create a user project"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Body parameters
Name, Type, Description
`name` string Required Name of the project
`body` string or null Body of the project

HTTP response status codes for "Create a user project"

Status code	Description
`201`	Created
`304`	Not modified
`401`	Requires authentication
`403`	Forbidden
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Create a user project"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/user/projects

curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/user/projects \ -d '{"name":"My Projects","body":"A board to manage my personal projects."}'

Response

Status: 201

{ "owner_url": "https://api.github.com/users/octocat", "url": "https://api.github.com/projects/1002603", "html_url": "https://github.com/users/octocat/projects/1", "columns_url": "https://api.github.com/projects/1002603/columns", "id": 1002603, "node_id": "MDc6UHJvamVjdDEwMDI2MDM=", "name": "My Projects", "body": "A board to manage my personal projects.", "number": 1, "state": "open", "creator": { "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 }, "created_at": "2011-04-10T20:09:31Z", "updated_at": "2014-03-03T18:58:10Z" }

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`username` string Required The handle for the GitHub user account.

Query parameters
Name, Type, Description
`state` string Indicates the state of the projects to return. Default: `open` Can be one of: `open`, `closed`, `all`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

HTTP response status codes for "List user projects"

Status code	Description
`200`	OK
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "List user projects"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/users/{username}/projects

curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/users/USERNAME/projects

Response

Status: 200

[ { "owner_url": "https://api.github.com/users/octocat", "url": "https://api.github.com/projects/1002603", "html_url": "https://github.com/users/octocat/projects/1", "columns_url": "https://api.github.com/projects/1002603/columns", "id": 1002603, "node_id": "MDc6UHJvamVjdDEwMDI2MDM=", "name": "My Projects", "body": "A board to manage my personal projects.", "number": 1, "state": "open", "creator": { "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 }, "created_at": "2011-04-10T20:09:31Z", "updated_at": "2014-03-03T18:58:10Z" } ]