GitHub Organizations API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub Projects Organizations API
  description: 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. This API is particularly useful for integrating project management functionality into custom applications, automating project updates based on repository events, building dashboards and reporting tools, or synchronizing GitHub project data with external project management systems.
  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: Organizations
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:
      - Organizations
      operationId: listOrganizationProjects
      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
      security:
      - bearerHttpAuthentication: []
      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:
      - Organizations
      operationId: createAnOrganizationProject
      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
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    nullable-simple-user:
      title: Simple User
      description: A GitHub user.
      type:
      - object
      - 'null'
      properties:
        name:
          type:
          - string
          - 'null'
          example: octocat
        email:
          type:
          - string
          - 'null'
          example: octocat@github.com
        login:
          type: string
          example: octocat
        id:
          type: integer
          example: 1
        node_id:
          type: string
          example: MDQ6VXNlcjE=
        avatar_url:
          type: string
          format: uri
          example: https://github.com/images/error/octocat_happy.gif
        gravatar_id:
          type:
          - string
          - 'null'
          example: 41d064eb2195891e12d0413f63227ea7
        url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
        html_url:
          type: string
          format: uri
          example: https://github.com/octocat
        followers_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/followers
        following_url:
          type: string
          example: https://api.github.com/users/octocat/following{/other_user}
        gists_url:
          type: string
          example: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url:
          type: string
          example: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/subscriptions
        organizations_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/orgs
        repos_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        events_url:
          type: string
          example: https://api.github.com/users/octocat/events{/privacy}
        received_events_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/received_events
        type:
          type: string
          example: User
        site_admin:
          type: boolean
          example: true
        starred_at:
          type: string
          example: '"2020-07-09T00:17:55Z"'
      required:
      - avatar_url
      - events_url
      - followers_url
      - following_url
      - gists_url
      - gravatar_id
      - html_url
      - id
      - node_id
      - login
      - organizations_url
      - received_events_url
      - repos_url
      - site_admin
      - starred_url
      - subscriptions_url
      - type
      - url
    validation-error-simple:
      title: Validation Error Simple
      description: Validation Error Simple
      type: object
      required:
      - message
      - documentation_url
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        errors:
          type: array
          items:
            type: string
    project:
      title: Project
      description: Projects are a way to organize columns and cards of work.
      type: object
      properties:
        owner_url:
          type: string
          format: uri
          example: https://api.github.com/repos/api-playground/projects-test
        url:
          type: string
          format: uri
          example: https://api.github.com/projects/1002604
        html_url:
          type: string
          format: uri
          example: https://github.com/api-playground/projects-test/projects/12
        columns_url:
          type: string
          format: uri
          example: https://api.github.com/projects/1002604/columns
        id:
          type: integer
          example: 1002604
        node_id:
          type: string
          example: MDc6UHJvamVjdDEwMDI2MDQ=
        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'
        number:
          type: integer
          example: 1
        state:
          description: State of the project; either 'open' or 'closed'
          example: open
          type: string
        creator:
          $ref: '#/components/schemas/nullable-simple-user'
        created_at:
          type: string
          format: date-time
          example: '2011-04-10T20:09:31Z'
        updated_at:
          type: string
          format: date-time
          example: '2014-03-03T18:58:10Z'
        organization_permission:
          description: The baseline permission that all organization members have on this project. Only present if owner is an organization.
          type: string
          enum:
          - read
          - write
          - admin
          - none
          example: read
        private:
          description: Whether or not this project can be seen by everyone. Only present if owner is an organization.
          type: boolean
          example: true
      required:
      - id
      - node_id
      - number
      - name
      - body
      - state
      - url
      - html_url
      - owner_url
      - creator
      - columns_url
      - created_at
      - updated_at
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        status:
          type: string
          example: open
  responses:
    validation_failed_simple:
      description: Validation failed, or the endpoint has been spammed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/validation-error-simple'
    gone:
      description: Gone
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    requires_authentication:
      description: Requires authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  examples:
    project-2:
      value:
        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'
    project-items:
      value:
      - owner_url: https://api.github.com/orgs/octocat
        url: https://api.github.com/projects/1002605
        html_url: https://github.com/orgs/api-playground/projects/1
        columns_url: https://api.github.com/projects/1002605/columns
        id: 1002605
        node_id: MDc6UHJvamVjdDEwMDI2MDU=
        name: Organization Roadmap
        body: High-level roadmap for the upcoming year.
        number: 1
        state: open
        creator:
          login: octocat
          id: 1
          node_id: MDQ6VXNlcjE=
          avatar_url: https://github.com/images/error/octocat_happy.gif
          gravatar_id: ''
          url: https://api.github.com/users/octocat
          html_url: https://github.com/octocat
          followers_url: https://api.github.com/users/octocat/followers
          following_url: https://api.github.com/users/octocat/following{/other_user}
          gists_url: https://api.github.com/users/octocat/gists{/gist_id}
          starred_url: https://api.github.com/users/octocat/starred{/owner}{/repo}
          subscriptions_url: https://api.github.com/users/octocat/subscriptions
          organizations_url: https://api.github.com/users/octocat/orgs
          repos_url: https://api.github.com/users/octocat/repos
          events_url: https://api.github.com/users/octocat/events{/privacy}
          received_events_url: https://api.github.com/users/octocat/received_events
          type: User
          site_admin: false
        created_at: '2011-04-11T20:09:31Z'
        updated_at: '2014-03-04T18:58:10Z'
        organization_permission: write
        private: true
  parameters:
    org:
      name: org
      description: The organization name. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    per-page:
      name: per_page
      description: The number of results per page (max 100). For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 30
    page:
      name: page
      description: The page number of the results to fetch. For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 1
  headers:
    link:
      example: <https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"
      schema:
        type: string
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer Token
      type: http
      scheme: Bearer
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/enterprise-server@3.9/rest/