The GitHub Projects API enables developers to programmatically create and manage GitHub Projects, which are flexible tools for planning and tracking work using customizable boards, tables, and roadmaps. Through these REST API endpoints, you can create projects at the repository, organization, or user level, add and organize items like issues and pull requests, manage project fields and views, update item statuses and metadata, and automate project workflows.
openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Projects API
description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App
installations.'
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
tags:
- name: Projects
description: Interact with GitHub Projects.
paths:
/orgs/{org}/projects:
get:
summary: GitHub List Organization Projects
description: 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.
tags:
- Projects
operationId: projects/list-for-org
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/projects#list-organization-projects
parameters:
- $ref: '#/components/parameters/org'
- name: state
description: Indicates the state of the projects to return.
in: query
required: false
schema:
type: string
enum:
- open
- closed
- all
default: open
example: open
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/project'
examples:
default:
$ref: '#/components/examples/project-items'
headers:
Link:
$ref: '#/components/headers/link'
'422':
$ref: '#/components/responses/validation_failed_simple'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: projects
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create an Organization Project
description: Creates an organization project board. Returns a `410 Gone` status if projects are disabled in the organization or if the organization does not have existing classic projects. If you do not have sufficient privileges to perform this action, a `401 Unauthorized` or `410 Gone` status is returned.
tags:
- Projects
operationId: projects/create-for-org
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/projects#create-an-organization-project
parameters:
- $ref: '#/components/parameters/org'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the project.
body:
type: string
description: The description of the project.
required:
- name
examples:
default:
value:
name: Organization Roadmap
body: High-level roadmap for the upcoming year.
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/project'
examples:
default:
$ref: '#/components/examples/project-2'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'410':
$ref: '#/components/responses/gone'
'422':
$ref: '#/components/responses/validation_failed_simple'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: projects
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/columns/cards/{card_id}:
get:
summary: GitHub Get a Project Card
description: Gets information about a project card.
tags:
- Projects
operationId: projects/get-card
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/cards#get-a-project-card
parameters:
- $ref: '#/components/parameters/card-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/project-card'
examples:
default:
$ref: '#/components/examples/project-card'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: cards
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update an Existing Project Card
description: ''
tags:
- Projects
operationId: projects/update-card
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/cards#update-an-existing-project-card
parameters:
- $ref: '#/components/parameters/card-id'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
note:
description: The project card's note
example: Update all gems
type: string
nullable: true
archived:
description: Whether or not the card is archived
example: false
type: boolean
examples:
default:
summary: Change the note on the card
value:
note: Add payload for delete Project column
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/project-card'
examples:
default:
$ref: '#/components/examples/project-card'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed_simple'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: cards
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete a Project Card
description: Deletes a project card
tags:
- Projects
operationId: projects/delete-card
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/cards#delete-a-project-card
parameters:
- $ref: '#/components/parameters/card-id'
responses:
'204':
description: Response
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
documentation_url:
type: string
errors:
type: array
items:
type: string
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: cards
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/columns/cards/{card_id}/moves:
post:
summary: GitHub Move a Project Card
description: ''
tags:
- Projects
operationId: projects/move-card
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/cards#move-a-project-card
parameters:
- $ref: '#/components/parameters/card-id'
requestBody:
required: true
content:
application/json:
schema:
properties:
position:
description: 'The position of the card in a column. Can be one of: `top`, `bottom`, or `after:<card_id>` to place after the specified card.'
example: bottom
type: string
pattern: ^(?:top|bottom|after:\d+)$
column_id:
description: The unique identifier of the column the card should be moved to
example: 42
type: integer
required:
- position
type: object
examples:
default:
summary: Move the card to the bottom of the column
value:
column_id: 42
position: bottom
responses:
'201':
description: Response
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
examples:
default:
value: null
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
documentation_url:
type: string
errors:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
resource:
type: string
field:
type: string
'422':
$ref: '#/components/responses/validation_failed'
'503':
description: Response
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
documentation_url:
type: string
errors:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: cards
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/columns/{column_id}:
get:
summary: GitHub Get a Project Column
description: Gets information about a project column.
tags:
- Projects
operationId: projects/get-column
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/columns#get-a-project-column
parameters:
- $ref: '#/components/parameters/column-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/project-column'
examples:
default:
$ref: '#/components/examples/project-column'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: columns
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update an Existing Project Column
description: ''
tags:
- Projects
operationId: projects/update-column
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/columns#update-an-existing-project-column
parameters:
- $ref: '#/components/parameters/column-id'
requestBody:
required: true
content:
application/json:
schema:
properties:
name:
description: Name of the project column
example: Remaining tasks
type: string
required:
- name
type: object
examples:
default:
summary: Rename the project column
value:
name: To Do
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/project-column'
examples:
default:
$ref: '#/components/examples/project-column'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: columns
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete a Project Column
description: Deletes a project column.
tags:
- Projects
operationId: projects/delete-column
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/columns#delete-a-project-column
parameters:
- $ref: '#/components/parameters/column-id'
responses:
'204':
description: Response
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: columns
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/columns/{column_id}/cards:
get:
summary: GitHub List Project Cards
description: Lists the project cards in a project.
tags:
- Projects
operationId: projects/list-cards
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/cards#list-project-cards
parameters:
- $ref: '#/components/parameters/column-id'
- name: archived_state
description: Filters the project cards that are returned by the card's state.
in: query
required: false
schema:
type: string
enum:
- all
- archived
- not_archived
default: not_archived
example: all
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/project-card'
examples:
default:
$ref: '#/components/examples/project-card-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: cards
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create a Project Card
description: ''
tags:
- Projects
operationId: projects/create-card
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/cards#create-a-project-card
parameters:
- $ref: '#/components/parameters/column-id'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
properties:
note:
description: The project card's note
example: Update all gems
type: string
nullable: true
required:
- note
- type: object
properties:
content_id:
description: The unique identifier of the content associated with the card
example: 42
type: integer
content_type:
description: The piece of content associated with the card
example: PullRequest
type: string
required:
- content_id
- content_type
examples:
default:
summary: Create a new card
value:
note: Add payload for delete Project column
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/project-card'
examples:
default:
$ref: '#/components/examples/project-card'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'422':
description: Validation failed
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/validation-error'
- $ref: '#/components/schemas/validation-error-simple'
'503':
description: Response
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
documentation_url:
type: string
errors:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: cards
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/columns/{column_id}/moves:
post:
summary: GitHub Move a Project Column
description: ''
tags:
- Projects
operationId: projects/move-column
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/columns#move-a-project-column
parameters:
- $ref: '#/components/parameters/column-id'
requestBody:
required: true
content:
application/json:
schema:
properties:
position:
description: 'The position of the column in a project. Can be one of: `first`, `last`, or `after:<column_id>` to place after the specified column.'
example: last
type: string
pattern: ^(?:first|last|after:\d+)$
required:
- position
type: object
examples:
default:
summary: Move the column to the end of the board
value:
position: last
responses:
'201':
description: Response
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
examples:
default:
value: null
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/validation_failed_simple'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: columns
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/{project_id}:
get:
summary: GitHub Get a Project
description: 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.
tags:
- Projects
operationId: projects/get
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/projects#get-a-project
parameters:
- $ref: '#/components/parameters/project-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/project'
examples:
default:
$ref: '#/components/examples/project-3'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: projects
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update a Project
description: 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.
operationId: projects/update
tags:
- Projects
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/projects#update-a-project
parameters:
- $ref: '#/components/parameters/project-id'
requestBody:
required: false
content:
application/json:
schema:
properties:
name:
description: Name of the project
example: Week One Sprint
type: string
body:
description: Body of the project
example: This project represents the sprint of the first week in January
type: string
nullable: true
state:
description: State of the project; either 'open' or 'closed'
example: open
type: string
organization_permission:
description: The baseline permission that all organization members have on this project
type: string
enum:
- read
- write
- admin
- none
private:
description: Whether or not this project can be seen by everyone.
type: boolean
type: object
examples:
default:
summary: Change the name, state, and permissions for a project
value:
name: Week One Sprint
state: open
organization_permission: write
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/project'
examples:
default:
$ref: '#/components/examples/project-3'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
documentation_url:
type: string
errors:
type: array
items:
type: string
'404':
description: Not Found if the authenticated user does not have access to the project
'410':
$ref: '#/components/responses/gone'
'422':
$ref: '#/components/responses/validation_failed_simple'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: projects
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete a Project
description: Deletes a project board. Returns a `404 Not Found` status if projects are disabled.
operationId: projects/delete
tags:
- Projects
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/projects#delete-a-project
parameters:
- $ref: '#/components/parameters/project-id'
responses:
'204':
description: Delete Success
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
documentation_url:
type: string
errors:
type: array
items:
type: string
'404':
$ref: '#/components/responses/not_found'
'410':
$ref: '#/components/responses/gone'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: projects
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/{project_id}/collaborators:
get:
summary: GitHub List Project Collaborators
description: 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.
tags:
- Projects
operationId: projects/list-collaborators
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/collaborators#list-project-collaborators
parameters:
- $ref: '#/components/parameters/project-id'
- name: affiliation
description: Filters the collaborators by their affiliation. `outside` means outside collaborators of a project that are not a member of the project's organization. `direct` means collaborators with permissions to a project, regardless of organization membership status. `all` means all collaborators the authenticated user can see.
in: query
required: false
schema:
type: string
enum:
- outside
- direct
- all
default: all
example: outside
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: projects
subcategory: collaborators
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/projects/{project_id}/collaborators/{username}:
put:
summary: GitHub Add Project Collaborator
description: 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.
tags:
- Projects
operationId: projects/add-collaborator
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/projects/collaborators#add-project-collaborator
parameters:
- $ref: '#/components/parameters/project-id'
- $ref: '#/components/parameters/username'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
# --- truncated at 32 KB (701 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-projects-api-openapi.yml