Puntos de conexión de API REST para campañas de seguridad

Nota:

Estos puntos de conexión solo interactúan con campañas publicadas. Actualmente, las campañas de borrador no se pueden ver ni administrar a través de la API.

List campaigns for an organization

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.

Tokens de acceso específicos para "List campaigns for an organization"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Campaigns" organization permissions (read)

Parámetros para "List campaigns for an organization"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.

Parámetros de consulta
Nombre, Tipo, Descripción
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Valor predeterminado: `1`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Valor predeterminado: `30`
`direction` string The direction to sort the results by. Valor predeterminado: `desc` Puede ser uno de los siguientes: `asc`, `desc`
`state` string If specified, only campaigns with this state will be returned. Puede ser uno de los siguientes: `open`, `closed`
`sort` string The property by which to sort the results. Valor predeterminado: `created` Puede ser uno de los siguientes: `created`, `updated`, `ends_at`, `published`

Códigos de estado de respuesta HTTP para "List campaigns for an organization"

status code	Descripción
`200`	OK
`404`	Resource not found
`503`	Service unavailable

Ejemplos de código para "List campaigns for an organization"

Ejemplo de solicitud

get/orgs/{org}/campaigns

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/campaigns

Response

Status: 200

[
  {
    "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"
  }
]

Create a campaign for an organization

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.

Tokens de acceso específicos para "Create a campaign for an organization"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Campaigns" organization permissions (write)

Parámetros para "Create a campaign for an organization"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.

Nombre, Tipo, Descripción

name string Requerido

The name of the campaign

description string Requerido

A description for the campaign

managers array of strings

The logins of the users to set as the campaign managers. At this time, only a single manager can be supplied.

team_managers array of strings

The slugs of the teams to set as the campaign managers.

ends_at string Requerido

The end date and time of the campaign. The date must be in the future.

contact_link string or null

The contact link of the campaign. Must be a URI.

code_scanning_alerts array of objects Requerido

The code scanning alerts to include in this campaign

Properties of code_scanning_alerts

Nombre, Tipo, Descripción
`repository_id` integer Requerido The repository id
`alert_numbers` array of integers Requerido The alert numbers

generate_issues boolean

If true, will automatically generate issues for the campaign. The default is false.

Valor predeterminado: false

Códigos de estado de respuesta HTTP para "Create a campaign for an organization"

status code	Descripción
`200`	OK
`400`	Bad Request
`404`	Resource not found
`422`	Unprocessable Entity
`429`	Too Many Requests
`503`	Service unavailable

Ejemplos de código para "Create a campaign for an organization"

Ejemplo de solicitud

post/orgs/{org}/campaigns

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/campaigns \
  -d '{"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]}]}'

Response

Status: 200

{
  "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
  }
}

Get a campaign for an organization

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.

Tokens de acceso específicos para "Get a campaign for an organization"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Campaigns" organization permissions (read)

Parámetros para "Get a campaign for an organization"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.
`campaign_number` integer Requerido The campaign number.

Códigos de estado de respuesta HTTP para "Get a campaign for an organization"

status code	Descripción
`200`	OK
`404`	Resource not found
`422`	Unprocessable Entity
`503`	Service unavailable

Ejemplos de código para "Get a campaign for an organization"

Ejemplo de solicitud

get/orgs/{org}/campaigns/{campaign_number}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/campaigns/CAMPAIGN_NUMBER

Response

Status: 200

{
  "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
  }
}

Update a campaign

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.

Tokens de acceso específicos para "Update a campaign"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Campaigns" organization permissions (write)

Parámetros para "Update a campaign"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.
`campaign_number` integer Requerido The campaign number.

Parámetros del cuerpo
Nombre, Tipo, Descripción
`name` string The name of the campaign
`description` string A description for the campaign
`managers` array of strings The logins of the users to set as the campaign managers. At this time, only a single manager can be supplied.
`team_managers` array of strings The slugs of the teams to set as the campaign managers.
`ends_at` string The end date and time of the campaign, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
`contact_link` string or null The contact link of the campaign. Must be a URI.
`state` string Indicates whether a campaign is open or closed Puede ser uno de los siguientes: `open`, `closed`

Códigos de estado de respuesta HTTP para "Update a campaign"

status code	Descripción
`200`	OK
`400`	Bad Request
`404`	Resource not found
`422`	Unprocessable Entity
`503`	Service unavailable

Ejemplos de código para "Update a campaign"

Ejemplo de solicitud

patch/orgs/{org}/campaigns/{campaign_number}

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/campaigns/CAMPAIGN_NUMBER \
  -d '{"name":"Critical CodeQL alerts"}'

Response

Status: 200

{
  "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
  }
}

Delete a campaign for an organization

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.

Tokens de acceso específicos para "Delete a campaign for an organization"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Campaigns" organization permissions (write)

Parámetros para "Delete a campaign for an organization"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.
`campaign_number` integer Requerido The campaign number.

Códigos de estado de respuesta HTTP para "Delete a campaign for an organization"

status code	Descripción
`204`	Deletion successful
`404`	Resource not found
`503`	Service unavailable

Ejemplos de código para "Delete a campaign for an organization"

Ejemplo de solicitud

delete/orgs/{org}/campaigns/{campaign_number}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/campaigns/CAMPAIGN_NUMBER

Deletion successful

Status: 204