GitHub Card API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub Projects Card 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: Card
paths:
  /projects/columns/cards/{card_id}:
    get:
      summary: GitHub Get Project Card
      description: The Get Project Card operation retrieves detailed information about a specific card within a GitHub Project board by providing its unique card identifier. This endpoint returns comprehensive data about the card including its note content, associated issue or pull request details, creation and update timestamps, creator information, and its current position within the project column. The card_id parameter is required in the URL path to specify which card to retrieve, and the response includes metadata such as the card's URL, node ID, and archived status. This operation is useful for programmatically accessing project card details for project management automation, reporting, or integration with external tools.
      tags:
      - Card
      operationId: getProjectCard
      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
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: GitHub Update an Existing Project Card
      description: The PATCH operation on the `/projects/columns/cards/{card_id}` endpoint allows you to modify an existing project card within a GitHub project board by providing the card's unique identifier. This API call enables you to update card properties such as the note content or archived status, giving you programmatic control over managing cards in your project workflows. You must authenticate with appropriate permissions to modify cards, and the endpoint returns the updated card object upon successful execution. This is particularly useful for automation scenarios where you need to dynamically update card information, move cards between states, or archive cards based on project progress without manually interacting with the GitHub web interface.
      tags:
      - Card
      operationId: updateAnExistingProjectCard
      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'
        '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
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Delete Project Card
      description: Deletes an existing card from a GitHub project board column by its unique card identifier. This operation permanently removes the specified project card and cannot be undone. The authenticated user must have write access to the repository or organization that owns the project board to successfully delete the card. Once deleted, the card and its associated metadata are removed from the project, though any linked issues or pull requests remain unaffected in their respective repositories.
      tags:
      - Card
      operationId: deleteProjectCard
      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
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /projects/columns/cards/{card_id}/moves:
    post:
      summary: GitHub Move Project Card
      description: This API operation moves a project card to a different position within the same column or to a different column entirely within a GitHub project board. When making a POST request to /projects/columns/cards/{card_id}/moves, you specify the card_id of the card you want to relocate and provide parameters in the request body to define the new position, such as the target column_id and the desired position relative to other cards (top, bottom, or after a specific card). This endpoint is useful for programmatically organizing and reordering cards within project boards, enabling automation of project management workflows and integration with external tools. The operation requires appropriate authentication and permissions to modify the project board, and upon success, it returns the updated card object with its new position information.
      tags:
      - Card
      operationId: moveProjectCard
      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
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /projects/columns/{column_id}/cards:
    post:
      summary: GitHub Create Project Card
      description: Creates a new card in the specified project column identified by column_id. This endpoint allows you to add either a content card (linked to an issue or pull request) or a note card (containing plain text) to a project board column. When creating a content card, you must provide the content_id and content_type parameters to reference an existing issue or pull request. For note cards, you supply a note parameter with the desired text content. The newly created card is added to the bottom of the specified column by default, though its position can be adjusted later. This operation requires appropriate repository or organization permissions depending on whether the project is repository-level or organization-level, and the authenticated user must have write access to the project.
      tags:
      - Card
      operationId: createProjectCard
      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'
        '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
      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:
      title: Validation Error
      description: Validation Error
      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: object
            required:
            - code
            properties:
              resource:
                type: string
              field:
                type: string
              message:
                type: string
              code:
                type: string
              index:
                type: integer
              value:
                oneOf:
                - type:
                  - string
                  - 'null'
                - type:
                  - integer
                  - 'null'
                - type:
                  - array
                  - 'null'
                  items:
                    type: string
    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-card:
      title: Project Card
      description: Project cards represent a scope of work.
      type: object
      properties:
        url:
          type: string
          format: uri
          example: https://api.github.com/projects/columns/cards/1478
        id:
          description: The project card's ID
          example: 42
          type: integer
        node_id:
          type: string
          example: MDExOlByb2plY3RDYXJkMTQ3OA==
        note:
          type:
          - string
          - 'null'
          example: Add payload for delete Project column
        creator:
          $ref: '#/components/schemas/nullable-simple-user'
        created_at:
          type: string
          format: date-time
          example: '2016-09-05T14:21:06Z'
        updated_at:
          type: string
          format: date-time
          example: '2016-09-05T14:20:22Z'
        archived:
          description: Whether or not the card is archived
          example: false
          type: boolean
        column_name:
          type: string
          example: octocat
        project_id:
          type: string
          example: '12345678'
        column_url:
          type: string
          format: uri
          example: https://api.github.com/projects/columns/367
        content_url:
          type: string
          format: uri
          example: https://api.github.com/repos/api-playground/projects-test/issues/3
        project_url:
          type: string
          format: uri
          example: https://api.github.com/projects/120
      required:
      - id
      - node_id
      - note
      - url
      - column_url
      - project_url
      - creator
      - 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'
    validation_failed:
      description: Validation failed, or the endpoint has been spammed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/validation-error'
    not_modified:
      description: Not modified
    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-card:
      value:
        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
  parameters:
    card-id:
      name: card_id
      description: The unique identifier of the card.
      in: path
      required: true
      schema:
        type: integer
    column-id:
      name: column_id
      description: The unique identifier of the column.
      in: path
      required: true
      schema:
        type: integer
  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/