The Wayback Machine - https://web.archive.org/web/20220313235225/https://docs.github.com/en/rest/reference/projects
Skip to main content
Free, Pro, & Team
English
Sign up
 
REST API
Free, Pro, & Team
English
Sign up

 

Projects

In this article

The Projects API lets you create, list, update, delete and customize projects in a repository.

List organization projects

Lists the projects in an organization. Returns a 404 Not Found status if projects are disabled in the organization. If you do not have sufficient privileges to perform this action, a 401 Unauthorized or 410 Gone status is returned.

get /orgs/{org}/projects

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

orgstringpath
statestringquery

Indicates the state of the projects to return. Can be either open, closed, or all.

Default: open

per_pageintegerquery

Results per page (max 100)

Default: 30

pageintegerquery

Page number of the results to fetch.

Default: 1

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/projects
JavaScript (@octokit/core.js)
 await octokit.request('GET /orgs/{org}/projects', {
  org: 'org'
})

Response

 Status: 200 OK
 [
  {
    "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"
  }
]

Validation failed

 Status: 422 Unprocessable Entity

Notes

Create an organization project

Creates an organization project board. Returns a 404 Not Found status if projects are disabled in the organization. If you do not have sufficient privileges to perform this action, a 401 Unauthorized or 410 Gone status is returned.

post /orgs/{org}/projects

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

orgstringpath
namestringbody

Required. The name of the project.

bodystringbody

The description of the project.

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/projects \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
 await octokit.request('POST /orgs/{org}/projects', {
  org: 'org',
  name: 'name'
})

Response

 Status: 201 Created
 {
  "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"
}

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Gone

 Status: 410 Gone

Validation failed

 Status: 422 Unprocessable Entity

Notes

Get a project

Gets a project by its id. Returns a 404 Not Found status if projects are disabled. If you do not have sufficient privileges to perform this action, a 401 Unauthorized or 410 Gone status is returned.

get /projects/{project_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42
JavaScript (@octokit/core.js)
 await octokit.request('GET /projects/{project_id}', {
  project_id: 42
})

Response

 Status: 200 OK
 {
  "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"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Notes

Update a project

Updates a project board's information. Returns a 404 Not Found status if projects are disabled. If you do not have sufficient privileges to perform this action, a 401 Unauthorized or 410 Gone status is returned.

patch /projects/{project_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath
namestringbody

Name of the project

bodystring or nullbody

Body of the project

statestringbody

State of the project; either 'open' or 'closed'

organization_permissionstringbody

The baseline permission that all organization members have on this project

privatebooleanbody

Whether or not this project can be seen by everyone.

Code samples

Shell
 curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
 await octokit.request('PATCH /projects/{project_id}', {
  project_id: 42,
  name: 'name'
})

Response

 Status: 200 OK
 {
  "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"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Not Found if the authenticated user does not have access to the project

 Status: 404 Not Found

Gone

 Status: 410 Gone

Validation failed

 Status: 422 Unprocessable Entity

Notes

Delete a project

Deletes a project board. Returns a 404 Not Found status if projects are disabled.

delete /projects/{project_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath

Code samples

Shell
 curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42
JavaScript (@octokit/core.js)
 await octokit.request('DELETE /projects/{project_id}', {
  project_id: 42
})

Delete Success

 Status: 204 No Content

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Gone

 Status: 410 Gone

Notes

List repository projects

Lists the projects in a repository. Returns a 404 Not Found status if projects are disabled in the repository. If you do not have sufficient privileges to perform this action, a 401 Unauthorized or 410 Gone status is returned.

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

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
statestringquery

Indicates the state of the projects to return. Can be either open, closed, or all.

Default: open

per_pageintegerquery

Results per page (max 100)

Default: 30

pageintegerquery

Page number of the results to fetch.

Default: 1

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/projects
JavaScript (@octokit/core.js)
 await octokit.request('GET /repos/{owner}/{repo}/projects', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

 Status: 200 OK
 [
  {
    "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"
  }
]

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Gone

 Status: 410 Gone

Validation failed

 Status: 422 Unprocessable Entity

Notes

Create a repository project

Creates a repository project board. Returns a 404 Not Found status if projects are disabled in the repository. If you do not have sufficient privileges to perform this action, a 401 Unauthorized or 410 Gone status is returned.

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

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
namestringbody

Required. The name of the project.

bodystringbody

The description of the project.

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/projects \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
 await octokit.request('POST /repos/{owner}/{repo}/projects', {
  owner: 'octocat',
  repo: 'hello-world',
  name: 'name'
})

Response

 Status: 201 Created
 {
  "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"
}

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Gone

 Status: 410 Gone

Validation failed

 Status: 422 Unprocessable Entity

Notes

Create a user project

post /user/projects

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

namestringbody

Required. Name of the project

bodystring or nullbody

Body of the project

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/projects \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
 await octokit.request('POST /user/projects', {
  name: 'name'
})

Response

 Status: 201 Created
 {
  "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"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Preview header missing

 Status: 415 Unsupported Media Type

Validation failed

 Status: 422 Unprocessable Entity

Notes

List user projects

get /users/{username}/projects

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

usernamestringpath
statestringquery

Indicates the state of the projects to return. Can be either open, closed, or all.

Default: open

per_pageintegerquery

Results per page (max 100)

Default: 30

pageintegerquery

Page number of the results to fetch.

Default: 1

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/projects
JavaScript (@octokit/core.js)
 await octokit.request('GET /users/{username}/projects', {
  username: 'username'
})

Response

 Status: 200 OK
 [
  {
    "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"
  }
]

Validation failed

 Status: 422 Unprocessable Entity

Cards

Get a project card

get /projects/columns/cards/{card_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

card_idintegerpath

card_id parameter

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/cards/42
JavaScript (@octokit/core.js)
 await octokit.request('GET /projects/columns/cards/{card_id}', {
  card_id: 42
})

Response

 Status: 200 OK
 {
  "url": "https://api.github.com/projects/columns/cards/1478",
  "id": 1478,
  "node_id": "MDExOlByb2plY3RDYXJkMTQ3OA==",
  "note": "Add payload for delete Project column",
  "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": "2016-09-05T14:21:06Z",
  "updated_at": "2016-09-05T14:20:22Z",
  "archived": false,
  "column_url": "https://api.github.com/projects/columns/367",
  "content_url": "https://api.github.com/repos/api-playground/projects-test/issues/3",
  "project_url": "https://api.github.com/projects/120"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Notes

Update an existing project card

patch /projects/columns/cards/{card_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

card_idintegerpath

card_id parameter

notestring or nullbody

The project card's note

archivedbooleanbody

Whether or not the card is archived

Code samples

Shell
 curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/cards/42 \
  -d '{"note":"note"}'
JavaScript (@octokit/core.js)
 await octokit.request('PATCH /projects/columns/cards/{card_id}', {
  card_id: 42,
  note: 'note'
})

Response

 Status: 200 OK
 {
  "url": "https://api.github.com/projects/columns/cards/1478",
  "id": 1478,
  "node_id": "MDExOlByb2plY3RDYXJkMTQ3OA==",
  "note": "Add payload for delete Project column",
  "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": "2016-09-05T14:21:06Z",
  "updated_at": "2016-09-05T14:20:22Z",
  "archived": false,
  "column_url": "https://api.github.com/projects/columns/367",
  "content_url": "https://api.github.com/repos/api-playground/projects-test/issues/3",
  "project_url": "https://api.github.com/projects/120"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Validation failed

 Status: 422 Unprocessable Entity

Notes

Delete a project card

delete /projects/columns/cards/{card_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

card_idintegerpath

card_id parameter

Code samples

Shell
 curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/cards/42
JavaScript (@octokit/core.js)
 await octokit.request('DELETE /projects/columns/cards/{card_id}', {
  card_id: 42
})

Response

 Status: 204 No Content

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Notes

Move a project card

post /projects/columns/cards/{card_id}/moves

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

card_idintegerpath

card_id parameter

positionstringbody

Required. The position of the card in a column. Can be one of: top, bottom, or after:<card_id> to place after the specified card.

column_idintegerbody

The unique identifier of the column the card should be moved to

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/cards/42/moves \
  -d '{"position":"position"}'
JavaScript (@octokit/core.js)
 await octokit.request('POST /projects/columns/cards/{card_id}/moves', {
  card_id: 42,
  position: 'position'
})

Response

 Status: 201 Created

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Validation failed

 Status: 422 Unprocessable Entity

Response

 Status: 503 Service Unavailable

Notes

List project cards

get /projects/columns/{column_id}/cards

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

column_idintegerpath

column_id parameter

archived_statestringquery

Filters the project cards that are returned by the card's state. Can be one of all,archived, or not_archived.

Default: not_archived

per_pageintegerquery

Results per page (max 100)

Default: 30

pageintegerquery

Page number of the results to fetch.

Default: 1

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/42/cards
JavaScript (@octokit/core.js)
 await octokit.request('GET /projects/columns/{column_id}/cards', {
  column_id: 42
})

Response

 Status: 200 OK
 [
  {
    "url": "https://api.github.com/projects/columns/cards/1478",
    "id": 1478,
    "node_id": "MDExOlByb2plY3RDYXJkMTQ3OA==",
    "note": "Add payload for delete Project column",
    "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": "2016-09-05T14:21:06Z",
    "updated_at": "2016-09-05T14:20:22Z",
    "archived": false,
    "column_url": "https://api.github.com/projects/columns/367",
    "content_url": "https://api.github.com/repos/api-playground/projects-test/issues/3",
    "project_url": "https://api.github.com/projects/120"
  }
]

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Notes

Create a project card

post /projects/columns/{column_id}/cards

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

column_idintegerpath

column_id parameter

notestring or nullbody

Required. The project card's note

content_idintegerbody

Required. The unique identifier of the content associated with the card

content_typestringbody

Required. The piece of content associated with the card

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/42/cards
JavaScript (@octokit/core.js)
 await octokit.request('POST /projects/columns/{column_id}/cards', {
  column_id: 42
})

Response

 Status: 201 Created
 {
  "url": "https://api.github.com/projects/columns/cards/1478",
  "id": 1478,
  "node_id": "MDExOlByb2plY3RDYXJkMTQ3OA==",
  "note": "Add payload for delete Project column",
  "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": "2016-09-05T14:21:06Z",
  "updated_at": "2016-09-05T14:20:22Z",
  "archived": false,
  "column_url": "https://api.github.com/projects/columns/367",
  "content_url": "https://api.github.com/repos/api-playground/projects-test/issues/3",
  "project_url": "https://api.github.com/projects/120"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Validation failed

 Status: 422 Unprocessable Entity

Response

 Status: 503 Service Unavailable

Notes

Collaborators

This API allows you to interact with an organization's projects.

List project collaborators

Lists the collaborators for an organization project. For a project, the list of collaborators includes outside collaborators, organization members that are direct collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners. You must be an organization owner or a project admin to list collaborators.

get /projects/{project_id}/collaborators

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath
affiliationstringquery

Filters the collaborators by their affiliation. Can be one of:
* outside: Outside collaborators of a project that are not a member of the project's organization.
* direct: Collaborators with permissions to a project, regardless of organization membership status.
* all: All collaborators the authenticated user can see.

Default: all

per_pageintegerquery

Results per page (max 100)

Default: 30

pageintegerquery

Page number of the results to fetch.

Default: 1

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42/collaborators
JavaScript (@octokit/core.js)
 await octokit.request('GET /projects/{project_id}/collaborators', {
  project_id: 42
})

Response

 Status: 200 OK
 [
  {
    "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
  }
]

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Validation failed

 Status: 422 Unprocessable Entity

Notes

Add project collaborator

Adds a collaborator to an organization project and sets their permission level. You must be an organization owner or a project admin to add a collaborator.

put /projects/{project_id}/collaborators/{username}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath
usernamestringpath
permissionstringbody

The permission to grant the collaborator.

Default: write

Code samples

Shell
 curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42/collaborators/USERNAME \
  -d '{"permission":"permission"}'
JavaScript (@octokit/core.js)
 await octokit.request('PUT /projects/{project_id}/collaborators/{username}', {
  project_id: 42,
  username: 'username',
  permission: 'permission'
})

Response

 Status: 204 No Content

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Validation failed

 Status: 422 Unprocessable Entity

Notes

Remove user as a collaborator

Removes a collaborator from an organization project. You must be an organization owner or a project admin to remove a collaborator.

delete /projects/{project_id}/collaborators/{username}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath
usernamestringpath

Code samples

Shell
 curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42/collaborators/USERNAME
JavaScript (@octokit/core.js)
 await octokit.request('DELETE /projects/{project_id}/collaborators/{username}', {
  project_id: 42,
  username: 'username'
})

Response

 Status: 204 No Content

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Validation failed

 Status: 422 Unprocessable Entity

Notes

Get project permission for a user

Returns the collaborator's permission level for an organization project. Possible values for the permission key: admin, write, read, none. You must be an organization owner or a project admin to review a user's permission level.

get /projects/{project_id}/collaborators/{username}/permission

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath
usernamestringpath

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42/collaborators/USERNAME/permission
JavaScript (@octokit/core.js)
 await octokit.request('GET /projects/{project_id}/collaborators/{username}/permission', {
  project_id: 42,
  username: 'username'
})

Response

 Status: 200 OK
 {
  "permission": "admin",
  "user": {
    "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
  }
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Validation failed

 Status: 422 Unprocessable Entity

Notes

Columns

Get a project column

get /projects/columns/{column_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

column_idintegerpath

column_id parameter

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/42
JavaScript (@octokit/core.js)
 await octokit.request('GET /projects/columns/{column_id}', {
  column_id: 42
})

Response

 Status: 200 OK
 {
  "url": "https://api.github.com/projects/columns/367",
  "project_url": "https://api.github.com/projects/120",
  "cards_url": "https://api.github.com/projects/columns/367/cards",
  "id": 367,
  "node_id": "MDEzOlByb2plY3RDb2x1bW4zNjc=",
  "name": "To Do",
  "created_at": "2016-09-05T14:18:44Z",
  "updated_at": "2016-09-05T14:22:28Z"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Notes

Update an existing project column

patch /projects/columns/{column_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

column_idintegerpath

column_id parameter

namestringbody

Required. Name of the project column

Code samples

Shell
 curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
 await octokit.request('PATCH /projects/columns/{column_id}', {
  column_id: 42,
  name: 'name'
})

Response

 Status: 200 OK
 {
  "url": "https://api.github.com/projects/columns/367",
  "project_url": "https://api.github.com/projects/120",
  "cards_url": "https://api.github.com/projects/columns/367/cards",
  "id": 367,
  "node_id": "MDEzOlByb2plY3RDb2x1bW4zNjc=",
  "name": "To Do",
  "created_at": "2016-09-05T14:18:44Z",
  "updated_at": "2016-09-05T14:22:28Z"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Notes

Delete a project column

delete /projects/columns/{column_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

column_idintegerpath

column_id parameter

Code samples

Shell
 curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/42
JavaScript (@octokit/core.js)
 await octokit.request('DELETE /projects/columns/{column_id}', {
  column_id: 42
})

Response

 Status: 204 No Content

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Notes

Move a project column

post /projects/columns/{column_id}/moves

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

column_idintegerpath

column_id parameter

positionstringbody

Required. The position of the column in a project. Can be one of: first, last, or after:<column_id> to place after the specified column.

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/columns/42/moves \
  -d '{"position":"position"}'
JavaScript (@octokit/core.js)
 await octokit.request('POST /projects/columns/{column_id}/moves', {
  column_id: 42,
  position: 'position'
})

Response

 Status: 201 Created

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Validation failed

 Status: 422 Unprocessable Entity

Notes

List project columns

get /projects/{project_id}/columns

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath
per_pageintegerquery

Results per page (max 100)

Default: 30

pageintegerquery

Page number of the results to fetch.

Default: 1

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42/columns
JavaScript (@octokit/core.js)
 await octokit.request('GET /projects/{project_id}/columns', {
  project_id: 42
})

Response

 Status: 200 OK
 [
  {
    "url": "https://api.github.com/projects/columns/367",
    "project_url": "https://api.github.com/projects/120",
    "cards_url": "https://api.github.com/projects/columns/367/cards",
    "id": 367,
    "node_id": "MDEzOlByb2plY3RDb2x1bW4zNjc=",
    "name": "To Do",
    "created_at": "2016-09-05T14:18:44Z",
    "updated_at": "2016-09-05T14:22:28Z"
  }
]

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Notes

Create a project column

post /projects/{project_id}/columns

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

project_idintegerpath
namestringbody

Required. Name of the project column

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/projects/42/columns \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
 await octokit.request('POST /projects/{project_id}/columns', {
  project_id: 42,
  name: 'name'
})

Response

 Status: 201 Created
 {
  "url": "https://api.github.com/projects/columns/367",
  "project_url": "https://api.github.com/projects/120",
  "cards_url": "https://api.github.com/projects/columns/367/cards",
  "id": 367,
  "node_id": "MDEzOlByb2plY3RDb2x1bW4zNjc=",
  "name": "To Do",
  "created_at": "2016-09-05T14:18:44Z",
  "updated_at": "2016-09-05T14:22:28Z"
}

Not modified

 Status: 304 Not Modified

Requires authentication

 Status: 401 Unauthorized

Forbidden

 Status: 403 Forbidden

Validation failed

 Status: 422 Unprocessable Entity

Notes

HTTPS · web.archive.org
← Home