APIs.io Engineering Platform Projects API

openapi: 3.2.0
info:
  version: 1.1.4
  title: APIs.io Engineering Platform GitHub v3 REST Projects API
  description: GitHub's v3 REST API.
  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: APIs.io Engineering Platform 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
      - $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
    post:
      summary: APIs.io Engineering Platform 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
  /projects/columns/cards/{card_id}:
    get:
      summary: APIs.io Engineering Platform 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'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: cards
    patch:
      summary: APIs.io Engineering Platform 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
                  - 'null'
                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'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed_simple'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: cards
    delete:
      summary: APIs.io Engineering Platform 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'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  documentation_url:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/requires_authentication'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: cards
  /projects/columns/cards/{card_id}/moves:
    post:
      summary: APIs.io Engineering Platform 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'
        '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
        '401':
          $ref: '#/components/responses/requires_authentication'
        '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
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: cards
  /projects/columns/{column_id}:
    get:
      summary: APIs.io Engineering Platform 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'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '401':
          $ref: '#/components/responses/requires_authentication'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: columns
    patch:
      summary: APIs.io Engineering Platform 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'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref: '#/components/responses/requires_authentication'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: columns
    delete:
      summary: APIs.io Engineering Platform 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'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref: '#/components/responses/requires_authentication'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: columns
  /projects/columns/{column_id}/cards:
    get:
      summary: APIs.io Engineering Platform 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
      - $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'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref: '#/components/responses/requires_authentication'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: cards
    post:
      summary: APIs.io Engineering Platform 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
                    - 'null'
                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'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '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
  /projects/columns/{column_id}/moves:
    post:
      summary: APIs.io Engineering Platform 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'
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/validation_failed_simple'
        '401':
          $ref: '#/components/responses/requires_authentication'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: columns
  /projects/{project_id}:
    get:
      summary: APIs.io Engineering Platform 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'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref: '#/components/responses/requires_authentication'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: projects
    patch:
      summary: APIs.io Engineering Platform 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
                  - 'null'
                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'
        '404':
          description: Not Found if the authenticated user does not have access to the project
        '304':
          $ref: '#/components/responses/not_modified'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  documentation_url:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/requires_authentication'
        '410':
          $ref: '#/components/responses/gone'
        '422':
          $ref: '#/components/responses/validation_failed_simple'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: projects
    delete:
      summary: APIs.io Engineering Platform 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'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  documentation_url:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/requires_authentication'
        '410':
          $ref: '#/components/responses/gone'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: projects
  /projects/{project_id}/collaborators:
    get:
      summary: APIs.io Engineering Platform 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
      - $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'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed'
        '304':
          $ref: '#/components/responses/not_modified'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref: '#/components/responses/requires_authentication'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: projects
        subcategory: collaborators
  /projects/{project_id}/collaborators/{username}:
    put:
      summary: APIs.io Engineering Platform 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
              - 'null'
              properties:
                permission:
                  description: The permission to grant the collaborator.
                  enum:
                  - read
                  - write
                  - admin
                  default: write
                  example: write
                  type: string
            examples:
              default:
                summary: Applying write permissions for the new collaborator
                value:
                  permission: write
      responses:
        '204':
          description: Response
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed'
        '304':
          $ref: '#/components/responses/not_modified'
        '403':
          $ref: '#/components/responses/forbidden'
        '401':
          $ref:

# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/engineering-platform/refs/heads/main/openapi/engineering-platform-projects-api-openapi.yml