GitHub Columns API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub Projects Columns 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: Columns
paths:
  /projects/columns/{column_id}/moves:
    post:
      summary: GitHub Move Project Column
      description: This API endpoint allows you to change the position of a project column within a GitHub project board by sending a POST request to /projects/columns/{column_id}/moves. You must specify the column_id in the URL path and provide the desired position in the request body, either as an absolute position using the "position" parameter (e.g., "first", "last", or a specific index) or relative to another column. The authenticated user must have write access to the project to perform this operation. This is useful for reorganizing project boards to better reflect workflow stages or priority order without having to recreate columns.
      tags:
      - Columns
      operationId: moveProjectColumn
      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
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /projects/{project_id}/columns:
    get:
      summary: GitHub List Project Columns
      description: This API endpoint retrieves all columns within a specified GitHub project board by providing the project's unique identifier in the URL path. When called with a GET request to /projects/{project_id}/columns, it returns an array of column objects containing details such as column names, identifiers, creation dates, and update timestamps for each column in the project. This operation is useful for developers who need to programmatically access the structure of a project board, enumerate available columns for task organization, or integrate project management data into external applications and workflows.
      tags:
      - Columns
      operationId: listProjectColumns
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/projects/columns#list-project-columns
      parameters:
      - $ref: '#/components/parameters/project-id'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/project-column'
              examples:
                default:
                  $ref: '#/components/examples/project-column-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: columns
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: GitHub Create Project Column
      description: Creates a new column in a GitHub project board by sending a POST request to the /projects/{project_id}/columns endpoint, where {project_id} is the unique identifier of the target project. This operation requires authentication and appropriate permissions to modify the project. The request body must include the column name and can optionally specify the column's position within the project board. Upon successful creation, the API returns a 201 status code along with the newly created column's details, including its unique column ID, name, project URL, and creation timestamp. This endpoint is useful for programmatically organizing project workflows by adding new stages or categories to track issues and pull requests.
      tags:
      - Columns
      operationId: createProjectColumn
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/projects/columns#create-a-project-column
      parameters:
      - $ref: '#/components/parameters/project-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:
                value:
                  name: Remaining tasks
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project-column'
              examples:
                default:
                  value:
                    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'
        '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
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    project-id:
      name: project_id
      description: The unique identifier of the project.
      in: path
      required: true
      schema:
        type: integer
    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
    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
    column-id:
      name: column_id
      description: The unique identifier of the column.
      in: path
      required: true
      schema:
        type: integer
  examples:
    project-column-items:
      value:
      - 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'
  responses:
    validation_failed_simple:
      description: Validation failed, or the endpoint has been spammed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/validation-error-simple'
    not_modified:
      description: Not modified
    requires_authentication:
      description: Requires authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  schemas:
    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
    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-column:
      title: Project Column
      description: Project columns contain cards of work.
      type: object
      properties:
        url:
          type: string
          format: uri
          example: https://api.github.com/projects/columns/367
        project_url:
          type: string
          format: uri
          example: https://api.github.com/projects/120
        cards_url:
          type: string
          format: uri
          example: https://api.github.com/projects/columns/367/cards
        id:
          description: The unique identifier of the project column
          example: 42
          type: integer
        node_id:
          type: string
          example: MDEzOlByb2plY3RDb2x1bW4zNjc=
        name:
          description: Name of the project column
          example: Remaining tasks
          type: string
        created_at:
          type: string
          format: date-time
          example: '2016-09-05T14:18:44Z'
        updated_at:
          type: string
          format: date-time
          example: '2016-09-05T14:22:28Z'
      required:
      - id
      - node_id
      - url
      - project_url
      - cards_url
      - name
      - created_at
      - updated_at
  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/