Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 UK1 US1-FED US2-FED

Create Linear issues for security findings

copy Copy pageCopied

Note: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.

POST https://api.ap1.datadoghq.com/api/v2/security/findings/linear_issueshttps://api.ap2.datadoghq.com/api/v2/security/findings/linear_issueshttps://api.datadoghq.eu/api/v2/security/findings/linear_issueshttps://api.ddog-gov.com/api/v2/security/findings/linear_issueshttps://api.us2.ddog-gov.com/api/v2/security/findings/linear_issueshttps://api.uk1.datadoghq.com/api/v2/security/findings/linear_issueshttps://api.datadoghq.com/api/v2/security/findings/linear_issueshttps://api.us3.datadoghq.com/api/v2/security/findings/linear_issueshttps://api.us5.datadoghq.com/api/v2/security/findings/linear_issues

Overview

Create Linear issues for security findings. This operation creates a case in Datadog and a Linear issue linked to that case for bidirectional sync between Datadog and Linear. You can create up to 50 Linear issues per request and associate up to 50 security findings per Linear issue. Security findings that are already attached to another Linear issue will be detached from their previous Linear issue and attached to the newly created Linear issue. This endpoint requires any of the following permissions:

  • security_monitoring_findings_write
  • appsec_vm_write

    • Request

    Body Data (required)

    Expand All

    Field

    Type

    Description

    data [required]

    [object]

    Array of Linear issue creation request data objects.

    attributes

    object

    Attributes of the Linear issue to create.

    assignee_id

    string

    Unique identifier of the Datadog user assigned to the Linear issue.

    description

    string

    Description of the Linear issue. If not provided, the description will be automatically generated.

    label_ids

    [string]

    Linear label IDs to set on the created issue.

    linear_project_id

    string

    Unique identifier of the Linear project to pin the issue to. If not provided, the issue is not associated with a Linear project.

    priority

    enum

    Datadog case priority mapped to the Linear issue priority. If not provided, the priority will be automatically set to "NOT_DEFINED". Allowed enum values: NOT_DEFINED,P1,P2,P3,P4,P5

    default: NOT_DEFINED

    title

    string

    Title of the Linear issue. If not provided, the title will be automatically generated.

    relationships

    object

    Relationships of the Linear issue to create.

    findings [required]

    object

    Security findings to create a Linear issue for.

    data

    [object]

    Array of security finding data objects.

    id [required]

    string

    Unique identifier of the security finding.

    type [required]

    enum

    Security findings resource type. Allowed enum values: findings

    default: findings

    project [required]

    object

    Case management project configured with the Linear integration. It is used to create the Linear issue.

    data [required]

    object

    Data object representing a case management project.

    id [required]

    string

    Unique identifier of the case management project.

    type [required]

    enum

    Projects resource type. Allowed enum values: projects

    default: projects

    type [required]

    enum

    Linear issues resource type. Allowed enum values: linear_issues

    default: linear_issues

    {
  "data": [
    {
      "attributes": {
        "assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0",
        "description": "A description of the Linear issue.",
        "label_ids": [
          "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
        ],
        "linear_project_id": "d4c3b2a1-6f5e-8b7a-0d9c-2f1e4a3b6c5d",
        "priority": "P4",
        "title": "A title for the Linear issue."
      },
      "relationships": {
        "findings": {
          "data": [
            {
              "id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
              "type": "findings"
            }
          ]
        },
        "project": {
          "data": {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "projects"
          }
        }
      },
      "type": "linear_issues"
    }
  ]
}

    Response

    Created

    List of case responses.

    Expand All

    Field

    Type

    Description

    data [required]

    [object]

    Array of case response data objects.

    attributes

    object

    Attributes of the case.

    archived_at

    date-time

    Timestamp of when the case was archived.

    assigned_to

    object

    User assigned to the case.

    data [required]

    object

    Relationship to user object.

    id [required]

    string

    A unique identifier that represents the user.

    type [required]

    enum

    Users resource type. Allowed enum values: users

    default: users

    attributes

    object

    Custom attributes associated with the case as key-value pairs where values are string arrays.

    <any-key>

    [string]

    closed_at

    date-time

    Timestamp of when the case was closed.

    created_at

    date-time

    Timestamp of when the case was created.

    creation_source

    string

    Source of the case creation.

    description

    string

    Description of the case.

    due_date

    string

    Due date of the case.

    insights

    [object]

    Insights of the case.

    ref

    string

    Reference of the insight.

    resource_id

    string

    Unique identifier of the resource. For example, the unique identifier of a security finding.

    type

    string

    Type of the resource. For example, the type of a security finding is "SECURITY_FINDING".

    jira_issue

    object

    Jira issue associated with the case.

    error_message

    string

    Error message if the Jira issue creation failed.

    result

    object

    Result of the Jira issue creation.

    account_id

    string

    Account ID of the Jira issue.

    issue_id

    string

    Unique identifier of the Jira issue.

    issue_key

    string

    Key of the Jira issue.

    issue_url

    string

    URL of the Jira issue.

    status

    string

    Status of the Jira issue creation. Can be "COMPLETED" if the Jira issue was created successfully, or "FAILED" if the Jira issue creation failed.

    key

    string

    Key of the case.

    linear_issue

    object

    Linear issue associated with the case.

    error_message

    string

    Error message if the Linear issue creation failed.

    result

    object

    Result of the Linear issue creation.

    account_id

    string

    Account ID of the Linear workspace.

    issue_id

    string

    Unique identifier of the Linear issue.

    issue_key

    string

    Key of the Linear issue.

    team_id

    string

    Team ID of the Linear issue.

    url

    string

    URL of the Linear issue.

    status

    string

    Status of the Linear issue creation. Can be "COMPLETED" if the Linear issue was created successfully, or "FAILED" if the Linear issue creation failed.

    modified_at

    date-time

    Timestamp of when the case was last modified.

    priority

    string

    Priority of the case.

    servicenow_ticket

    object

    ServiceNow ticket associated with the case.

    result

    object

    Result of the ServiceNow ticket creation or attachment.

    instance_name

    string

    ServiceNow instance name extracted from the ticket URL.

    sys_id

    string

    Unique identifier of the ServiceNow incident record.

    sys_target_link

    string

    Direct link to the ServiceNow incident record.

    sys_target_sys_id

    string

    Unique identifier of the target ServiceNow record.

    table_name

    string

    ServiceNow table containing the incident record.

    url

    string

    URL of the ServiceNow incident record.

    status

    string

    Status of the ServiceNow ticket operation. Can be "COMPLETED" if successful, or "FAILED" if the operation failed.

    status

    string

    Status of the case.

    status_group

    string

    Status group of the case.

    status_name

    string

    Status name of the case.

    title

    string

    Title of the case.

    type

    string

    Type of the case. For security cases, this is always "SECURITY".

    id

    string

    Unique identifier of the case.

    relationships

    object

    Relationships of the case.

    created_by

    object

    User who created the case.

    data [required]

    object

    Relationship to user object.

    id [required]

    string

    A unique identifier that represents the user.

    type [required]

    enum

    Users resource type. Allowed enum values: users

    default: users

    modified_by

    object

    User who last modified the case.

    data [required]

    object

    Relationship to user object.

    id [required]

    string

    A unique identifier that represents the user.

    type [required]

    enum

    Users resource type. Allowed enum values: users

    default: users

    project

    object

    Project in which the case was created.

    data [required]

    object

    Data object representing a case management project.

    id [required]

    string

    Unique identifier of the case management project.

    type [required]

    enum

    Projects resource type. Allowed enum values: projects

    default: projects

    type [required]

    enum

    Cases resource type. Allowed enum values: cases

    default: cases

    {
  "data": [
    {
      "attributes": {
        "archived_at": "2025-01-01T00:00:00.000Z",
        "assigned_to": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "attributes": {
          "<any-key>": []
        },
        "closed_at": "2025-01-01T00:00:00.000Z",
        "created_at": "2025-01-01T00:00:00.000Z",
        "creation_source": "CS_SECURITY_FINDING",
        "description": "A description of the case.",
        "due_date": "2025-01-01",
        "insights": [
          {
            "ref": "/security/appsec/vm/library/vulnerability/dfa027f7c037b2f77159adc027fecb56?detection=static",
            "resource_id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
            "type": "SECURITY_FINDING"
          }
        ],
        "jira_issue": {
          "error_message": "{\"errorMessages\":[\"An error occured.\"],\"errors\":{}}",
          "result": {
            "account_id": "463a8631-680e-455c-bfd3-3ed04d326eb7",
            "issue_id": "2871276",
            "issue_key": "PROJ-123",
            "issue_url": "https://domain.atlassian.net/browse/PROJ-123"
          },
          "status": "COMPLETED"
        },
        "key": "PROJ-123",
        "linear_issue": {
          "error_message": "Linear issue creation failed.",
          "result": {
            "account_id": "463a8631-680e-455c-bfd3-3ed04d326eb7",
            "issue_id": "9c1e5f8a-2b3d-4c7e-8f6a-1d2e3f4a5b6c",
            "issue_key": "ENG-123",
            "team_id": "b5d3c8a1-7e6f-4d2c-9a8b-3c4d5e6f7a8b",
            "url": "https://linear.app/your-workspace/issue/ENG-123"
          },
          "status": "COMPLETED"
        },
        "modified_at": "2025-01-01T00:00:00.000Z",
        "priority": "P4",
        "servicenow_ticket": {
          "result": {
            "instance_name": "example",
            "sys_id": "abcdef0123456789abcdef0123456789",
            "sys_target_link": "https://example.service-now.com/incident.do?sys_id=abcdef0123456789abcdef0123456789",
            "sys_target_sys_id": "abcdef0123456789abcdef0123456789",
            "table_name": "incident",
            "url": "https://example.service-now.com/now/nav/ui/classic/params/target/incident.do?sys_id=abcdef0123456789abcdef0123456789"
          },
          "status": "COMPLETED"
        },
        "status": "OPEN",
        "status_group": "SG_OPEN",
        "status_name": "Open",
        "title": "A title for the case.",
        "type": "SECURITY"
      },
      "id": "c1234567-89ab-cdef-0123-456789abcdef",
      "relationships": {
        "created_by": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "modified_by": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "project": {
          "data": {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "projects"
          }
        }
      },
      "type": "cases"
    }
  ]
}

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                      ## default
# 

    # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/security/findings/linear_issues" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": [
    {
      "attributes": {
        "assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0",
        "description": "A description of the Linear issue.",
        "label_ids": [
          "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
        ],
        "linear_project_id": "d4c3b2a1-6f5e-8b7a-0d9c-2f1e4a3b6c5d",
        "priority": "NOT_DEFINED",
        "title": "A title for the Linear issue."
      },
      "relationships": {
        "findings": {
          "data": [
            {
              "id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
              "type": "findings"
            }
          ]
        },
        "project": {
          "data": {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "projects"
          }
        }
      },
      "type": "linear_issues"
    }
  ]
}
EOF