REST API endpoints for Projects (classic)
Use the REST API to create and manage projects (classic) in a repository.
Note
The REST API to manage projects (classic) only supports authentication using a personal access token (classic). For more information, see Managing your personal access tokens.
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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Projects" organization permissions (read)
Parameters for "List organization projects"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
Name, Type, Description |
---|
state string Indicates the state of the projects to return. Default: Can be one of: |
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: |
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"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/projects
Response
Status: 200
[
{
"owner_url": "https://HOSTNAME/orgs/octocat",
"url": "https://HOSTNAME/projects/1002605",
"html_url": "https://github.com/orgs/api-playground/projects/1",
"columns_url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Projects" organization permissions (write)
Parameters for "Create an organization project"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
Name, Type, Description |
---|
name string RequiredThe 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"
Request example
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/projects \
-d '{"name":"Organization Roadmap","body":"High-level roadmap for the upcoming year."}'
Response
Status: 201
{
"owner_url": "https://HOSTNAME/orgs/octocat",
"url": "https://HOSTNAME/projects/1002605",
"html_url": "https://github.com/orgs/api-playground/projects/1",
"columns_url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
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"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
project_id integer RequiredThe 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"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/projects/PROJECT_ID
Response
Status: 200
{
"owner_url": "https://HOSTNAME/repos/api-playground/projects-test",
"url": "https://HOSTNAME/projects/1002604",
"html_url": "https://github.com/api-playground/projects-test/projects/1",
"columns_url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
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"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
project_id integer RequiredThe unique identifier of the project. |
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: |
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"
Request example
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/projects/PROJECT_ID \
-d '{"name":"Week One Sprint","state":"open","organization_permission":"write"}'
Response
Status: 200
{
"owner_url": "https://HOSTNAME/repos/api-playground/projects-test",
"url": "https://HOSTNAME/projects/1002604",
"html_url": "https://github.com/api-playground/projects-test/projects/1",
"columns_url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
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"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
project_id integer RequiredThe 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"
Request example
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
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"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
owner string RequiredThe account owner of the repository. The name is not case sensitive. |
repo string RequiredThe name of the repository without the |
Name, Type, Description |
---|
state string Indicates the state of the projects to return. Default: Can be one of: |
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: |
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"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/projects
Response
Status: 200
[
{
"owner_url": "https://HOSTNAME/repos/api-playground/projects-test",
"url": "https://HOSTNAME/projects/1002604",
"html_url": "https://github.com/api-playground/projects-test/projects/1",
"columns_url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Projects" repository permissions (write)
Parameters for "Create a repository project"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
owner string RequiredThe account owner of the repository. The name is not case sensitive. |
repo string RequiredThe name of the repository without the |
Name, Type, Description |
---|
name string RequiredThe 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"
Request example
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/projects \
-d '{"name":"Projects Documentation","body":"Developer documentation project for the developer site."}'
Response
Status: 201
{
"owner_url": "https://HOSTNAME/repos/api-playground/projects-test",
"url": "https://HOSTNAME/projects/1002604",
"html_url": "https://github.com/api-playground/projects-test/projects/1",
"columns_url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/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"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
name string RequiredName 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"
Request example
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/user/projects \
-d '{"name":"My Projects","body":"A board to manage my personal projects."}'
Response
Status: 201
{
"owner_url": "https://HOSTNAME/users/octocat",
"url": "https://HOSTNAME/projects/1002603",
"html_url": "https://github.com/users/octocat/projects/1",
"columns_url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/octocat/received_events",
"type": "User",
"site_admin": false
},
"created_at": "2011-04-10T20:09:31Z",
"updated_at": "2014-03-03T18:58:10Z"
}
List user 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 user projects"
This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.
Parameters for "List user projects"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
username string RequiredThe handle for the GitHub user account. |
Name, Type, Description |
---|
state string Indicates the state of the projects to return. Default: Can be one of: |
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: |
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"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/users/USERNAME/projects
Response
Status: 200
[
{
"owner_url": "https://HOSTNAME/users/octocat",
"url": "https://HOSTNAME/projects/1002603",
"html_url": "https://github.com/users/octocat/projects/1",
"columns_url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://HOSTNAME/users/octocat/followers",
"following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
"gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
"starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
"organizations_url": "https://HOSTNAME/users/octocat/orgs",
"repos_url": "https://HOSTNAME/users/octocat/repos",
"events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
"received_events_url": "https://HOSTNAME/users/octocat/received_events",
"type": "User",
"site_admin": false
},
"created_at": "2011-04-10T20:09:31Z",
"updated_at": "2014-03-03T18:58:10Z"
}
]