Create Watch

Description: Creates a new Watch.

Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can create a Watch using this REST API in the scope of a project, by using the additional query parameter projectKey. A Watch can include both Global and Project Policies.

Security: Requires the "Manage Watches" role to be set on the User or Group level.

Usage: POST /xray/api/v2/watches

Consumes: application/json

Produces: application/json

Path parameters: None

Query Parameters:

Request Body:

GeneralDataObj:

ProjectResourcesObj:

ResourceObj:

FilterObj:

PatternObj:

KeyValueObj:

AssignedPolicyObj:

TicketGenerationObj:

DuplicateTicketCreationObj:

VersionTicketSettingsObj:

ImpactPathProfileMappingObj:

IncludeObj:

Response Body

Response Codes

Example Requests

Example 1 - Watch a Repository

{
    "general_data": {
        "name": "example1-watch",
        "description": "This is an example watch #1",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "repository",
                "bin_mgr_id": "default",
                "name": "libs-release-local",
                "filters": [
                    {
                        "type": "regex",
                        "value": ".*"
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "medium_vuln_policy",
            "type": "security"
        }
    ],
    "watch_recipients":["mymail@acme.com","sec@acme.com"]
}

Example 2 - Watch All Repositories

{
    "general_data": {
        "name": "all-repositories",
        "description": "This is a new watch for all repositories",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "all-repos",
                "filters": [
                    {
                        "type": "package-type",
                        "value": "Docker"
                    },
                    {
                        "type": "package-type",
                        "value": "Debian"
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "critial_issues",
            "type": "security"
        }
    ],
    "watch_recipients":["mymail@acme.com","umac@youremail.com"]
}

Example 3 - Watch a Build

{
    "general_data": {
        "name": "specific-build-watch",
        "description": "This is a new watch for a specific build",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "build",
                "name": "release-pipeline"
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "critial_issues",
            "type": "security"
        },
        {
            "name": "block_policy",
            "type": "security"
        }
    ],
    "watch_recipients":["mymail@acme.com","umac@youremail.com"]
}

Example 4- Watch all Builds

{
    "general_data": {
        "name": "build-watch",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "all-builds",
                "filters": [
                    {
                        "type": "ant-patterns",
                        "value":{
                            "ExcludePatterns": ["a*","b*"],
                            "IncludePatterns": ["ab*"]
                        }
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "test-license-policy-allowed-12956",
            "type": "license"
        }
    ],
    "watch_recipients":["mymail@acme.com","umac@youremail.com"]
}

Example 5 - Watch a Release Bundle V2

{
    "general_data": {
        "name": "specific-bundle-watch",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "releaseBundleV2",
                "bin_mgr_id": "default",
                "name": "release-pipeline"
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "block_policy",
            "type": "security"
        }
    ]
}

Example 6 - Watch all Release Bundle V2

{
    "general_data": {
        "name": "bundles-watch",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "all-releaseBundlesV2",
                "bin_mgr_id": "default"
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "test-license-policy-allowed-12956",
            "type": "license"
        }
    ]
}

Example 7 - Watch Projects by Project Key

{
    "general_data": {
        "name": "single_project_watch",
        "description": "This is a new watch for single project",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "project",
                "name": "myproject"
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ],
    "watch_recipients": [
        "mymaila@acme.com",
        "umac@youremail.com"
    ]
}

Example 8 - Watch All Projects

{
    "general_data": {
        "name": "vuln-prod",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "all-projects"
            }
        ]
     }
  ],
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ],
    "watch_recipients":["mymail@acme.com","umac@youremail.com"]
}

Example 9 - Watch Projects with Include/Exclude Patterns on all Projects

{
    "general_data": {
        "name": "vuln-prod",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "all-projects",
                "bin_mgr_id": "default",
                "filters": [
                    {
                        "type": "ant-patterns",
                        "value": {
                            "ExcludePatterns": [
                                "a*",
                                "b*"
                            ],
                            "IncludePatterns": [
                                "ab*"
                            ]
                        }
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ],
    "watch_recipients": [
        "mymail@acme.com",
        "umac@youremail.com"
    ]
}

Example 10 - Create Watch with Jira Integration Enabled on multiple resource types

{
    "general_data": {
        "name": "example-watch",
        "active": true,
        "description": "This is an example watch"
    },
    "project_resources": {
        "resources": [
            {
                "type": "repository",
                "name": "docker-local",
                "filters": [
                    {
                        "type": "path-ant-patterns",
                        "value": {
                            "IncludePatterns": [
                                "***"
                            ],
                            "ExcludePatterns": [
                                "**b*"
                            ]
                        }
                    },
                    {
                        "type": "package-type",
                        "value": "Docker"
                    }
                ],
                "repo_type": "local"
            },
            {
                "type": "releaseBundle",
                "name": "example-build"
            },
            {
                "type": "build",
                "name": "example-rb",
                "build_repo": "builds"
            },
            {
                "type": "releaseBundleV2",
                "name": "example-rbv2",
                "build_repo": "release-bundles-v2"
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "demo-security",
            "type": "security"
        }
    ],
    "watch_recipients": [
        "mymail@acme.com"
    ],
    "create_ticket_enabled": true,
    "ticket_profile": "Profile-example",
    "ticket_generation": {
        "create_duplicate_tickets": {
            "by_version": {
                "build": true,
                "package": true,
                "release_bundle": true
            }
        },
        "impact_path_profiles_mapping": {
            "include": [
                {
                    "profile": "ProjectA-profile",
                    "pattern": "*a/*"
                },
                {
                    "profile": "ProjectB-profile",
                    "pattern": "*b/*"
                }
            ]
        }
    }
}

Example 11 - Create a Watch in the Project Scope

POST /xray/api/v2/watches?projectKey=myproject

Example 12 - Watch a specific Git Repository

{
    "general_data": {
        "name": "example-watch",
        "description": "Watch git repository",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "bin_mgr_id": "default",
                "type": "gitRepository",
                "name": "github.com/my-org/my-git-repo.git"
            }
        ]
    },
    "assigned_policies": [
        {
            "bin_mgr_id": "default",
            "name": "my_git_policy",
            "type": "security"
        }
    ]
}

Example 13 - Watch a Git Organization excluding a specific repository

{
    "general_data": {
        "name": "example-watch",
        "description": "Watch git organization excluding a specific repository",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "bin_mgr_id": "default",
                "type": "gitRepository",
                "name": "github.com/my-org",
                "filters": [
                    {
                        "type": "ant-patterns",
                        "value": {
                            "ExcludePatterns": [
                                "github.com/my-org/repo-to-exclude.git"
                            ]
                        }
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "my_git_policy",
            "type": "security"
        }
    ]
}

Example Responses

Successful response:

201 Created
{
    "info": "Watch has been successfully created"
}

Error Response:

409 Conflict
{
    "error": "Watch already exists"
}