GitHub Enterprise Campaigns API

openapi: 3.2.0
info:
  title: Github Enterprise Campaigns API
  version: 1.1.4
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  x-github-plan: ghec
  description: 'Operations tagged campaigns across 2 of this provider''s published API definitions: github-enterprise-ghec-openapi.json, github-enterprise-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.github.com
tags:
- name: Campaigns
  description: Endpoints to manage campaigns via the REST API.
paths:
  /orgs/{org}/campaigns:
    get:
      summary: List campaigns for an organization
      description: 'Lists campaigns in an organization.


        The authenticated user must be an owner or security manager for the organization to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `security_events` scope to use this endpoint.'
      tags:
      - Campaigns
      operationId: campaigns/list-org-campaigns
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/campaigns/campaigns#list-campaigns-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/direction'
      - name: state
        description: If specified, only campaigns with this state will be returned.
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/campaign-state'
      - name: sort
        description: The property by which to sort the results.
        in: query
        required: false
        schema:
          type: string
          enum:
          - created
          - updated
          - ends_at
          - published
          default: created
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/campaign-summary'
              examples:
                default:
                  $ref: '#/components/examples/campaign-org-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '404':
          $ref: '#/components/responses/not_found'
        '503':
          $ref: '#/components/responses/service_unavailable'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: campaigns
        subcategory: campaigns
    post:
      summary: Create a campaign for an organization
      description: 'Create a campaign for an organization.


        The authenticated user must be an owner or security manager for the organization to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `security_events` scope to use this endpoint.


        Fine-grained tokens must have the "Code scanning alerts" repository permissions (read) on all repositories included

        in the campaign.'
      tags:
      - Campaigns
      operationId: campaigns/create-campaign
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/campaigns/campaigns#create-a-campaign-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  description: The name of the campaign
                  type: string
                  minLength: 1
                  maxLength: 50
                description:
                  description: A description for the campaign
                  type: string
                  minLength: 1
                  maxLength: 255
                managers:
                  description: The logins of the users to set as the campaign managers. At this time, only a single manager can be supplied.
                  type: array
                  maxItems: 10
                  items:
                    description: The login of each manager
                    type: string
                team_managers:
                  description: The slugs of the teams to set as the campaign managers.
                  type: array
                  maxItems: 10
                  items:
                    description: The slug of each team
                    type: string
                ends_at:
                  description: The end date and time of the campaign. The date must be in the future.
                  type: string
                  format: date-time
                contact_link:
                  description: The contact link of the campaign. Must be a URI.
                  type:
                  - string
                  - 'null'
                  format: uri
                code_scanning_alerts:
                  description: The code scanning alerts to include in this campaign
                  type:
                  - array
                  - 'null'
                  minItems: 1
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      repository_id:
                        type: integer
                        description: The repository id
                      alert_numbers:
                        type: array
                        description: The alert numbers
                        minItems: 1
                        items:
                          type: integer
                    required:
                    - repository_id
                    - alert_numbers
                generate_issues:
                  description: If true, will automatically generate issues for the campaign. The default is false.
                  type: boolean
                  default: false
              required:
              - name
              - description
              - ends_at
              oneOf:
              - required:
                - code_scanning_alerts
              - required:
                - secret_scanning_alerts
            examples:
              default:
                value:
                  name: Critical CodeQL alerts
                  description: Address critical alerts before they are exploited to prevent breaches, protect sensitive data, and mitigate financial and reputational damage.
                  managers:
                  - octocat
                  ends_at: '2024-03-14T00:00:00Z'
                  code_scanning_alerts:
                  - repository_id: 1296269
                    alert_numbers:
                    - 1
                    - 2
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/campaign-summary'
              examples:
                default:
                  $ref: '#/components/examples/campaign-summary'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basic-error'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basic-error'
        '429':
          description: Too Many Requests
        '503':
          $ref: '#/components/responses/service_unavailable'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: campaigns
        subcategory: campaigns
    servers:
    - url: https://api.github.com
  /orgs/{org}/campaigns/{campaign_number}:
    get:
      summary: Get a campaign for an organization
      description: 'Gets a campaign for an organization.


        The authenticated user must be an owner or security manager for the organization to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `security_events` scope to use this endpoint.'
      tags:
      - Campaigns
      operationId: campaigns/get-campaign-summary
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/campaigns/campaigns#get-a-campaign-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      - name: campaign_number
        description: The campaign number.
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/campaign-summary'
              examples:
                default:
                  $ref: '#/components/examples/campaign-summary'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basic-error'
        '503':
          $ref: '#/components/responses/service_unavailable'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: campaigns
        subcategory: campaigns
    patch:
      summary: Update a campaign
      description: 'Updates a campaign in an organization.


        The authenticated user must be an owner or security manager for the organization to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `security_events` scope to use this endpoint.'
      tags:
      - Campaigns
      operationId: campaigns/update-campaign
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/campaigns/campaigns#update-a-campaign
      parameters:
      - $ref: '#/components/parameters/org'
      - name: campaign_number
        description: The campaign number.
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  description: The name of the campaign
                  type: string
                  minLength: 1
                  maxLength: 50
                description:
                  description: A description for the campaign
                  type: string
                  minLength: 1
                  maxLength: 255
                managers:
                  description: The logins of the users to set as the campaign managers. At this time, only a single manager can be supplied.
                  type: array
                  maxItems: 10
                  items:
                    type: string
                team_managers:
                  description: The slugs of the teams to set as the campaign managers.
                  type: array
                  maxItems: 10
                  items:
                    description: The slug of each team
                    type: string
                ends_at:
                  description: The end date and time of the campaign, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
                  type: string
                  format: date-time
                contact_link:
                  description: The contact link of the campaign. Must be a URI.
                  type:
                  - string
                  - 'null'
                  format: uri
                state:
                  $ref: '#/components/schemas/campaign-state'
            examples:
              default:
                value:
                  name: Critical CodeQL alerts
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/campaign-summary'
              examples:
                default:
                  $ref: '#/components/examples/campaign-summary'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basic-error'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basic-error'
        '503':
          $ref: '#/components/responses/service_unavailable'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: campaigns
        subcategory: campaigns
    delete:
      summary: Delete a campaign for an organization
      description: 'Deletes a campaign in an organization.


        The authenticated user must be an owner or security manager for the organization to use this endpoint.


        OAuth app tokens and personal access tokens (classic) need the `security_events` scope to use this endpoint.'
      tags:
      - Campaigns
      operationId: campaigns/delete-campaign
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-cloud@latest/rest/campaigns/campaigns#delete-a-campaign-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      - name: campaign_number
        description: The campaign number.
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Deletion successful
        '404':
          $ref: '#/components/responses/not_found'
        '503':
          $ref: '#/components/responses/service_unavailable'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: campaigns
        subcategory: campaigns
    servers:
    - url: https://api.github.com
components:
  responses:
    service_unavailable:
      description: Service unavailable
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              documentation_url:
                type: string
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  parameters:
    org:
      name: org
      description: The organization name. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    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-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 1
    direction:
      name: direction
      description: The direction to sort the results by.
      in: query
      required: false
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
    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-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 30
  headers:
    link:
      example: <https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"
      schema:
        type: string
  schemas:
    nullable-team-simple:
      title: Team Simple
      description: Groups of organization members that gives permissions on specified repositories.
      type:
      - object
      - 'null'
      properties:
        id:
          description: Unique identifier of the team
          type: integer
          example: 1
        node_id:
          type: string
          example: MDQ6VGVhbTE=
        url:
          description: URL for the team
          type: string
          format: uri
          example: https://api.github.com/organizations/1/team/1
        members_url:
          type: string
          example: https://api.github.com/organizations/1/team/1/members{/member}
        name:
          description: Name of the team
          type: string
          example: Justice League
        description:
          description: Description of the team
          type:
          - string
          - 'null'
          example: A great team.
        permission:
          description: Permission that the team will have for its repositories
          type: string
          example: admin
        privacy:
          description: The level of privacy this team should have
          type: string
          example: closed
        notification_setting:
          description: The notification setting the team has set
          type: string
          example: notifications_enabled
        html_url:
          type: string
          format: uri
          example: https://github.com/orgs/rails/teams/core
        repositories_url:
          type: string
          format: uri
          example: https://api.github.com/organizations/1/team/1/repos
        slug:
          type: string
          example: justice-league
        ldap_dn:
          description: Distinguished Name (DN) that team maps to within LDAP environment
          example: uid=example,ou=users,dc=github,dc=com
          type: string
        type:
          description: The ownership type of the team
          type: string
          enum:
          - enterprise
          - organization
        organization_id:
          type: integer
          description: Unique identifier of the organization to which this team belongs
          example: 37
        enterprise_id:
          type: integer
          description: Unique identifier of the enterprise to which this team belongs
          example: 42
      required:
      - id
      - node_id
      - url
      - members_url
      - name
      - description
      - permission
      - html_url
      - repositories_url
      - slug
      - type
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
        documentation_url:
          type: string
        url:
          type: string
        status:
          type: string
    campaign-summary:
      title: Campaign summary
      description: The campaign metadata and alert stats.
      type: object
      properties:
        number:
          type: integer
          description: The number of the newly created campaign
        created_at:
          type: string
          format: date-time
          description: The date and time the campaign was created, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
        updated_at:
          type: string
          format: date-time
          description: The date and time the campaign was last updated, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
        name:
          type: string
          description: The campaign name
        description:
          type: string
          description: The campaign description
        managers:
          description: The campaign managers
          type: array
          items:
            $ref: '#/components/schemas/simple-user'
        team_managers:
          description: The campaign team managers
          type: array
          items:
            $ref: '#/components/schemas/team'
        published_at:
          description: The date and time the campaign was published, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
          type: string
          format: date-time
        ends_at:
          description: The date and time the campaign has ended, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
          type: string
          format: date-time
        closed_at:
          description: The date and time the campaign was closed, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ. Will be null if the campaign is still open.
          type:
          - string
          - 'null'
          format: date-time
        state:
          $ref: '#/components/schemas/campaign-state'
        contact_link:
          description: The contact link of the campaign.
          type:
          - string
          - 'null'
          format: uri
        alert_stats:
          type: object
          additionalProperties: false
          properties:
            open_count:
              type: integer
              description: The number of open alerts
            closed_count:
              type: integer
              description: The number of closed alerts
            in_progress_count:
              type: integer
              description: The number of in-progress alerts
          required:
          - open_count
          - closed_count
          - in_progress_count
      required:
      - number
      - created_at
      - updated_at
      - description
      - managers
      - ends_at
      - state
      - contact_link
    campaign-state:
      title: Campaign state
      description: Indicates whether a campaign is open or closed
      type: string
      enum:
      - open
      - closed
    team:
      title: Team
      description: Groups of organization members that gives permissions on specified repositories.
      type: object
      properties:
        id:
          type: integer
        node_id:
          type: string
        name:
          type: string
        slug:
          type: string
        description:
          type:
          - string
          - 'null'
        privacy:
          type: string
        notification_setting:
          type: string
        permission:
          type: string
        permissions:
          type: object
          properties:
            pull:
              type: boolean
            triage:
              type: boolean
            push:
              type: boolean
            maintain:
              type: boolean
            admin:
              type: boolean
          required:
          - pull
          - triage
          - push
          - maintain
          - admin
        url:
          type: string
          format: uri
        html_url:
          type: string
          format: uri
          example: https://github.com/orgs/rails/teams/core
        members_url:
          type: string
        repositories_url:
          type: string
          format: uri
        type:
          description: The ownership type of the team
          type: string
          enum:
          - enterprise
          - organization
        access_source:
          description: 'How the team''s access to the repository was granted. This property is only

            present when the team is returned in a repository context, such as

            `GET /repos/{owner}/{repo}/teams`.'
          type: string
          enum:
          - direct
          - organization
          - enterprise
          example: direct
        organization_id:
          type: integer
          description: Unique identifier of the organization to which this team belongs
          example: 37
        enterprise_id:
          type: integer
          description: Unique identifier of the enterprise to which this team belongs
          example: 42
        parent:
          $ref: '#/components/schemas/nullable-team-simple'
      required:
      - id
      - node_id
      - url
      - members_url
      - name
      - description
      - permission
      - html_url
      - repositories_url
      - slug
      - parent
      - type
    simple-user:
      title: Simple User
      description: A GitHub user.
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        login:
          type: string
          example: octocat
        id:
          type: integer
          format: int64
          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
        starred_at:
          type: string
          example: '"2020-07-09T00:17:55Z"'
        user_view_type:
          type: string
          example: public
      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
  examples:
    campaign-summary:
      value:
        number: 3
        created_at: '2024-02-14T12:29:18Z'
        updated_at: '2024-02-14T12:29:18Z'
        name: Critical CodeQL alert
        description: Address critical alerts before they are exploited to prevent breaches, protect sensitive data, and mitigate financial and reputational damage.
        managers:
        - 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
        published_at: '2024-02-14T12:29:18Z'
        ends_at: '2024-03-14T12:29:18Z'
        closed_at: null
        state: open
        alert_stats:
          open_count: 10
          closed_count: 3
          in_progress_count: 3
    campaign-org-items:
      value:
      - number: 3
        created_at: '2024-02-14T12:29:18Z'
        updated_at: '2024-02-14T12:29:18Z'
        name: Critical CodeQL alert
        description: Address critical alerts before they are exploited to prevent breaches, protect sensitive data, and mitigate financial and reputational damage.
        managers:
        - 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
        ends_at: '2024-03-14T12:29:18Z'
        closed_at: null
        state: open
      - number: 4
        created_at: '2024-03-30T12:29:18Z'
        updated_at: '2024-03-30T12:29:18Z'
        name: Mitre top 10 KEV
        description: Remediate the MITRE Top 10 KEV (Known Exploited Vulnerabilities) to enhance security by addressing vulnerabilities actively exploited by attackers. This reduces risk, prevents breaches and can help protect sensitive data.
        managers:
        - 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
        ends_at: '2024-04-30T12:29:18Z'
        closed_at: null
        state: open
externalDocs:
  description: GitHub Enterprise Cloud REST API
  url: https://docs.github.com/enterprise-cloud@latest/rest/
x-refined-from:
- github-enterprise-ghec-openapi.json
- github-enterprise-openapi.yml