Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

Xray provides a convenient and up-to-date self-descriptive API that can be used by various tools/frameworks to automate the creation of REST calls. 

Usage

Xray REST API endpoints can be invoked in any of the standard ways to invoke a RESTful API. This section describes how to use the Artifactory REST API using cURL as an example.

Using and Configuring cURL

You can download cURL here. Learn how to use and configure cURL here.

Base URL

http://<xrayhost>:<port>/api/v1  

Authentication

Most REST API calls need to be authenticated using your Xray user and password or through an authentication token. A few calls (such as SYSTEM calls) do not require authentication.

Example - Deleting a Watch

The example below demonstrates how to invoke the Delete Watch REST API with the following assumptions:

  • You are using cURL from the unix command line, and are presently working from the home (~) directory of the user 'myUser':

  • You wish to delete the watch called performance-watch.

  • You have Xray running on your local system, on port 8000.

  • You have configured a user in Xray named 'myUser', with password 'myP455w0rd!'.

  • You have an authentication token with value 12345

To execute a call using basic authentication you would run:

curl -u myUser:myP455w0rd! -X DELETE http://localhost:8000/api/v1/watches/performance-watch

To execute a call authenticating with a token you would run:

curl X DELETE http://localhost:8000/api/v1/watches/performance-watch?token=12345

Component Identifiers

Several endpoints require the use of a component identifier which must be formatted, according to its package type, using the convention described in the following table:

REST Resources

USER MANAGEMENT

Create User

Description: Creates a new Xray User. 
Security:  Requires an admin user
Usage: POST /users
Consumes: application/json

{
  "admin": <true | false>,
  "email": "",
  "name": "",
  "password": ""
}

Response Codes: 
200: Success - User created
400: Cannot create user with suffix _xray
409: User with name {name} already exists 

415: Failed to parse request
500: Failed to check if user exists in the database
500: Failed to marshal response 


Update User

Description: Updates an Xray User. 
Security:  Requires an admin user
Usage: POST /users/{id}
Consumes: application/json

{
  "admin": <true | false>,
  "email": "",
  "name": "",
  "password": ""
}

Response Codes: 
200: Success - User updated
400: Failed to update a new user
400: Mail format is not valid
404: Failed to find user
415: Failed to parse request


Get Users/ Get User

Description: Gets a list of all users in the system or a specific user
Security:  Requires an admin user
Usage: GET /users | GET /user/{id}
Produces: application/json

[
{
  "admin": <true | false>,
  "email": "",
  "name": "",
  "password": ""
}
]

Response Codes: 
200: Success
404: Use with id {id} does not exist
500: Failed to serialize user data
500: Failed to retrieve user 
500: Failed to retrieve user {id} 


Delete User

Description: Deletes a user
Security:  Requires an admin user
Usage: DELETE /users/{id}
Response Codes: 
200: Success - user was deleted
403: User cannot delete itself {id}
404: Failed to retrieve user {id}
500: User "admin" cannot be deleted


ISSUES

Create Issue Event

Description: Allows an issue vendor to create a new issue event 
Security:  Requires a valid user
Usage: POST /events
Consumes: application/json

{
	"type" : "<issue type>",
	"source_id" : "<vendor unique identifier>",
	"url" : "<url for issue information>",
	"created" : "<creation date in ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
	"description" : "Description of the event",
	"provider" : "The provider of the issue",
	"severity": "",
	"source_id": "",
	"summary": "",
	"updated": "<update time in ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
	"modified": "<modification time in ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
	"components" : //A list of components affected with this issue
		[
			{
				"component_id" : "<component unique identifier>",
				"properties" : {["key" : "value"]}
			}
		],
	"properties" : {["key" : "value"]}
}

Response: 201
Sample usage: 

POST /events
{
  "type": "security",
  "source_id": "574eb686ee6061000b7a6429",
  "url": "http://more.info",
  "created": "2016-05-03T07:30:51.991",
  "Components": [
    {
      "component_id": "gav://org.apache.maven:maven-settings:3.0.4",
      "properties": {
        "performance": false
      }
    }
  ],
  "properties": {
    "cve": "CVE-2012-2098",
    "summary": "Algorithmic complexity issue",
    "description": "Algorithmic complexity issue in...",
    "cvss_v2": "critical"
  }
}

Page Contents

 


Update Issue Event

Description: Allows an issue vendor to update an issue event 
Security:  Requires a valid user
Usage: PUT /events
Consumes: application/json

{
	"type" : "<issue type>",
	"source_id" : "<vendor unique identifier>",
	"url" : "<url for issue information>",
	"created" : "<creation date in ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
	"components" : //A list of components affected with this issue
		[
			{
				"component_id" : "<component unique identifier>",
				"properties" : {["key" : "value"]}
			}
		],
	"properties" : {["key" : "value"]}
}

Response: 201
Sample usage: 

PUT /events/574eb686ee6061000b7a6429

{
  "type": "security",
  "source_id": "574eb686ee6061000b7a6429",
  "url": "http://more.info",
  "created": "2016-05-03T07:30:51.991",
  "Components": [
    {
      "component_id": "gav://org.apache.maven:maven-settings:3.0.4",
      "properties": {
        "performance": false
      }
    }
  ],
  "properties": {
    "cve": "CVE-2012-2098",
    "summary": "Algorithmic complexity issue",
    "description": "Algorithmic complexity issue in...",
    "cvss_v2": "critical"
  }
}

Get Issue Events

Description: Gets an issue created by a vendor
Security:  Requires a valid user
Usage: GET /events/{sourceId}
Produces: application/json
Response: 201
Sample usage: 

GET /events/574eb686ee6061000b7a6429
 
{
	"type": "security",
  	"source_id": "574eb686ee6061000b7a6429",
  	"url": "http://more.info",
  	"created": "2015-11-03T07:30:51.991",
  	"Components": [
    {
    	"component_id": "gav://org.apache.maven:maven-settings:3.0.4",
    	"properties": { "performance": false }
    }
  	],
  	"properties": {
   	 	"cve": "CVE-2012-2098",
    	"summary": "Algorithmic complexity issue",
    	"description": "Algorithmic complexity issue in...",
    	"cvss_v2": "critical"
  	}
}

WATCHES

Create Watch

Description: Creates a new Watch. Mandatory fields are "name" and "target_type". If "target_type" is not "artifact" then "target_name" is also mandatory.
Security:  Requires a valid user
Usage: POST /watches
Consumes: application/json

{
  "active": <true | false>,
  "alerts": 5,
  "art_id": "",
  "description": "",
  "filters": [
    {
      "type": <"regex" | "mime-type" | "build" | "property" | "package-type" | "aql" | "license-black" | "license-white" | "issue-severity">,
      "value": "interface"
    }
  ],
  "id": "",
  "name": "",
  "post_actions": {
    "emails": [
      ""
    ],
    "slacks": "",
    "webhooks": [
      ""
    ],
	"fail_build":<true|false>
  },
  "repo_type": "",
  "severity": "",
  "system": <true | false>,
  "target_name": "",
  "target_type": "<"repository" | "build" | "artifact"| "builds">",
  "temp": <true | false>
}

Response Codes: 
200: Success - Watch created
415: Failed to parse request
400: Watch is not valid. Check mandatory fields
400: Binary manager doesn't exist
409: Watch with name {name} already exists 


Update Watch

Description: Updates a Watch. For system watches, only the filters can be updated.
Security:  Requires an admin user for a system watch, a valid user for a user defined watch
Usage: PUT /watches/{name}
Consumes: application/json (Please refer to Create Watch)
Sample usage: 
(Please refer to Create Watch)
Response Codes:
200: Success. Watch was successfully updated 
403: System watch is not editable for non-admin users
404: Failed to update watch. Watch was not found
415: Failed to parse watch
400: Failed to update watch 
500: Failed to update watch  


Get Watches / Get Watch

Description: Gets a list of all watches in the system or a named watch
Security:  Requires a valid user
Usage: GET /watches | GET /watches/{name}
Produces: application/json

[
{
  "active": <true | false>,
  "alerts": 10,
  "art_id": "",
  "description": "",
  "filters": [
      "type": <"regex" | "mime-type" | "build" | "property" | "package-type" | "aql" | "license-black" | "license-white" | "issue-severity">,
      "value": "interface"
  ],
  "id": "",
  "name": "",
  "post_actions": {
    "emails": [
      ""
    ],
    "slacks": "",
    "webhooks": [
      ""
    ],
	"fail_build":<true|false>
  },
  "repo_type": "",
  "severity": "",
  "system": <true | false>,
  "target_name": "",
  "target_type": "<"repository" | "build" | "artifact"| "builds">",
  "temp": <true | false>
}
]

Sample usage: 

GET /watches/Apache-2.0%20-%20banned?token=12345
 
{
  "id": "581f320e40a1632602462bb1",
  "name": "Apache-2.0 - banned",
  "description": "",
  "art_id": "",
  "active": true,
  "post_actions": {
    "emails": [],
    "webhooks": [],
	"fail_build":<true|false>
  },
  "filters": [
    {
      "type": "license-black",
      "value": [
        "Apache-2.0"
      ]
    }
  ],
  "target_type": "artifact",
  "alerts": 0
}

Response Codes:
200: Success
500: Failed to get watches 


Delete Watch

Description: Deletes a watch
Security:  Requires a valid user
Usage: DELETE /watches/{watch_name}

Produces: application/json

{
  "active": <true | false>,
  "alerts": 10,
  "art_id": "",
  "description": "",
  "filters": [
    {
      "type":"",
      "value":""
    }
  ],
  "id": "",
  "name": "",
  "post_actions": {
    "emails": [
      ""
    ],
    "slacks": "",
    "webhooks": [
      ""
    ],
	"fail_build":<true|false>
  },
  "repo_type": "",
  "severity": "",
  "system": <true | false>,
  "target_name": "",
  "target_type": "",
  "temp": <true | false>
}


Response Codes: 

200: Success - watch(es) deleted

400: Failed to delete watches 


ALERTS

Get User Alerts

Description: Gets all current alerts for a user
Security:  Requires a valid user
Usage: GET /alerts?offset=<num_of_alerts_to_skip>&limit=<max_alerts_to_display>&direction=<asc | desc>&order_by=<created_at | target | top_severity | watch_name>
Produces: application/json

[
	{
    	"created_at": "<creation date in ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",	
		"top_severity": "<top severity for all issues reported in the alert>",
		"watch_name": "<The name of the watch for which this alert was issued>",
		"issues" : [
      	{
	        "severity" : "<severity of the issue>",
        		"type" : "<issue type>",
        		"provider" : "<feed provider>",
        		"created": "<creation date in ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
        		"summary" : "<Summary of the issue>",
        		"component_ids" : ["<component_id>"],
				"description" : "<More detailed description of the issue>",				
				"impacted_artifacts" : [
				{
					"name": "<file name>",
					"display_name": "<name as displayed in Artifactory>",
					"path": "<file path in repository>",
					"pkg_type": "<The package type of the artifact for which this alert was issued>",			
					"sha256": "<file SHA256 checksum>",
					"sha1": "<file SHA1 checksum>",
					"depth": "<file depth in impact path>",
					"parentSha": "<SHA256 checksum of parent file>",	
		            "impact_path:": "<path to the infected file>",
           			"infected_file": {
              			"name": "<infected file name>",
						"path": "<infected file name>",
              			"sha256": "<infected file SHA256 checksum>",
              			"sha1": "<infected file SHA1 checksum>",
						"depth": "<infected file depth in impact path>",
              			"parent_sha": "<parent artifact file SHA256 checksum>",
						"display_name": "<infected file name as displayed in Artifactory>",
            			"pkg_type": "<infected file package type>"
           			}
          		}
       		]
    	}
    ]
  }
]

Sample usage:

GET /alerts?offset=0&limit=25&order_by=created_at&direction=desc
 
Response:
  "data": [
    {
      "created": "2016-12-07T14:12:08.466Z",
      "top_severity": "Critical",
      "watch_name": "new-watch",
      "issues": [
        {
          "severity": "Major",
          "type": "security",
          "provider": "WhiteSource",
          "created": "0001-01-01T00:00:00Z",
          "summary": "FileSystemBytecodeCache in Jinja2 2.7.2 does not properly create temporary directories",
          "component_ids": [
            "pypi://Jinja2:2.7.2"
          ],
          "description": "FileSystemBytecodeCache in Jinja2 2.7.2 does not properly create temporary directories, which allows local users to gain privileges by pre-creating a temporary directory with a user's uid.  NOTE: this vulnerability exists because of an incomplete fix for CVE-2014-1402.",
          "impacted_artifacts": [
            {
              "name": "Jinja2-2.7.2.tar.gz",
              "display_name": "Jinja2:2.7.2",
              "path": "artifactory-xray/Python/",
              "pkg_type": "Pypi",
              "sha256": "310a35fbccac3af13ebf927297f871ac656b9da1d248b1fe6765affa71b53235",
              "sha1": "",
              "depth": 0,
              "parent_sha": "310a35fbccac3af13ebf927297f871ac656b9da1d248b1fe6765affa71b53235",
              "impact_path": "",
              "infected_file": {
                "name": "Jinja2-2.7.2.tar.gz",
                "path": "###art12/Python/",
                "sha256": "310a35fbccac3af13ebf927297f871ac656b9da1d248b1fe6765affa71b53235",
                "sha1": "",
                "depth": 0,
                "parent_sha": "310a35fbccac3af13ebf927297f871ac656b9da1d248b1fe6765affa71b53235",
                "display_name": "Jinja2:2.7.2",
                "pkg_type": "Pypi"
              }
            }
        ]
      }
    ]
  }
]

Response Codes:

200: Success - Alerts found
400: Failed to get alerts. Check pagination query parameters.
404: No alerts found
500: Failed to read alerts


Ack Alert

Description: Acknowledge an existing alert
Security:  Requires a valid user
Usage: POST /alerts/ack
Produces: application/json
{
	"alert_Ids" : ["<alertId>", "<alertId>",...]
}

Sample usage:

 

POST /alerts/ack
 
Response
{
	"alert_Ids":["576a80bf8571664b691f0c07"]
}

Response Codes:

200: Alert has been acknowledged
404: Acknowledged alert not found
500: Failed to acknowledge alert


SCAN

Scan Artifact

Description: Invokes scanning of an artifact
Security:  Requires a valid user
Usage: POST /scanArtifact
Consumes: application/json

 

{
  "checksum": {
    "md5": "",
    "sha1": "",
    "sha256": ""
  },
  "componentId": "",
  "summary": ""
}

Response Codes:

200: Scan of artifact is in progress
415: Failed to parse artifact
500: Failed to write message to the queue


Run History Scan

Description: Invokes history scanning of indexed artifact
Security:  Requires a valid user
Usage: POST /historyScan 
consumes: application/json

{
  "from_date": "<start date in int64 format> ",
  "to_date": "<end date in int64 format>",
  "watch_id": "<The id of the watch according to which alerts should be issued>"
}

Block Download Setup

Description: Configures download blocking for a repository 
Security:  Requires an admin user
Usage: POST /blockDownloadSetup 
consumes: application/json

{
  "artifactoryId": "<The ID of the Artifactory instance>",
  "repoKey": "<The repository key in the specified Artifactory instance>",
  "severity": "<The severity of issues found for which downloads should be blocked>"
}

Update Block Download Setup

Description: Updates download blocking configuration for a repository
Security:  Requires an admin user
Usage: POST /blockDownloadSetup/{name}?watcher_name=<watcher name> 
consumes: application/json
{
  "artifactoryId": "",
  "repoKey": "",
  "severity": ""
}

Scan Build

Description: Invokes scanning of a build that was uploaded to Artifactory as requested by a CI server
Security:  Requires an admin user
Usage: POST /scanBuild
Consumes: application/json
Produces: wild card 

 

{
 "artifactoryId":<Artifactory instance id>,
 "buildName":<build name>,
 "buildNumber": <build number>
}

Produces: application/json

{
  "summary": {
    "fail_build": <true | false>,
    "message": <message with more information regarding the fail/success>,
    "more_details_url": <link to all created Alerts in Xray>,
    "total_alerts": <number of alerts generated from the scan>
  },
  "alerts": [  <alert details>
    {
      "created": <creation time of the Alert>,
      "issues": [ <the issues the Alert includes>
        {
          "created": <creation time of the issue>,
          "cve": "",
          "description": <issue description>,
          "impacted_artifacts": [
            {
              "depth": "int",
              "display_name": "",
              "infected_files": [
                {
                  "component_id": "",
                  "depth": "int",
                  "details": [
                    {
                      "banned_licenses": [
                        {
                          "alert_type": "",
                          "description": "",
                          "id": {},
                          "severity": "",
                          "summary": ""
                        }
                      ],
                      "child": "ImpactedFile",
                      "vulnerabilities": [
                        {
                          "alert_type": "",
                          "description": "",
                          "id": {},
                          "severity": "",
                          "summary": ""
                        }
                      ]
                    }
                  ],
                  "display_name": "",
                  "name": "",
                  "parent_sha": "",
                  "path": "",
                  "pkg_type": "",
                  "sha1": "",
                  "sha256": ""
                }
              ],
              "name": "",
              "parent_sha": "",
              "path": "",
              "pkg_type": "",
              "sha1": "",
              "sha256": ""
            }
          ],
          "provider": <issue provider>,
          "severity": <issue severity>,
          "summary": <issue summary>,
          "type": <issue type>
        }
      ],
      "top_severity": <Alert's top severity>,
      "watch_name": <name of the Watch which caused the Alert>
    }
  ],
  "licenses": [
    {
      "name": <license name>
      "components": [<names of build components with this license>],
      "full_name": <license full name>,
      "more_info_url": [<links to more information about this license>],
    }
  ]
}
Response Codes: 
200: Build scanned
415: Failed to parse scan build request
400: Request is missing mandatory fields
403: No valid license was found
500: Failed to get Artifactory instance data
500: Failed to check watches
500: Failed to send build to scan

AUTHORIZATION

Get Token

Description: Generates a temporary token that is valid for 2 hours
Security:  Requires a valid user
Usage: POST /auth/token
Consumes: application/json

 

{
  "name": "",
  "password": ""
}

Sample usage:

POST /auth/token
 
Response
{
  "admin": true,
  "email": "admin@mycompany.com",
  "token": "12345",
  "userName": "admin"
}

Response Codes:

200: Success
415: Bad credentials
500: Failed to marshal response


BINARY MANAGERS

Create Artifactory Configuration

Description: Configures a new connection to an Artifactory instance 
Security:  Requires an admin user
Usage: POST /binMgr
Consumes: application/json

 

{
  "binMgrDesc": "",
  "binMgrId": "",
  "binMgrUrl": "",
  "password": "",
  "proxy_enabled": <true | false>,
  "user": ""
}


Response Codes:

200: Artifactory instance has been successfully added
400: Failed to create new instance of Artifactory, id is missing
400: Artifactory url cannot contain localhost
401: Bad Credentials
409: Artifactory already exists
409: Artifactory with Id {id} or url {url} already exists
415: Failed to parse request
415: Artifactory id must not contain /
500: Failed to obtain a response
500: Failed to set Artifactory Xray support information
500: Failed to upload Xray compatibility plugin
500: Incompatible version: {version}. This Xray version only supports integration with Artifactory {supportVersion} and above.
500: Failed to check Artifactory configuration
500: Artifactory instances older than version 4.11 must the Enterprise with a valid license
500: Failed to add Artifactory instance to database
500: Failed to create Xray configuration for Artifactory
500: Failed to validate Artifactory license


Get Artifactory Configurations

Description: Gets the details of all connected Artifactory instances
Security:  Requires a valid user
Usage: GET /binMgr

Sample usage:

 

GET /binMgr
 
[
  {
    "binMgrDesc": "",
    "binMgrId": "",
    "binMgrUrl": "",
    "id": "",
    "license_expired": false,
    "license_valid": false,
    "proxy_enabled": false,
    "repos": [
      {
        "name": "",
        "pkgType": "",
        "type": ""
      }
    ],
    "version": ""
  }
]



Response codes:

200: List of Artifactory instances
401: Bad Credentials
500: Failed to obtain response


Update Backward Compatibility Plugin 

Description: Updates the Xray backward compatibility plugin to support versions of Artifactory older than 4.11
Security:  Requires an admin user
Usage: POST /updateBinMgrPlugin

Response codes:

200: Xray compatibility plugin has been successfully installed
500: Failed to update Xray compatibility plugin


Update Instance

Description: Updates the details of a connected Artifactory instance
Security:  Requires an admin user
Usage: PUT /binMgr/{id}
Consumes: application/json

 

{
  "binMgrDesc": "",
  "binMgrId": "",
  "binMgrUrl": "",
  "password": "",
  "proxy_enabled": <true | false>,
  "user": ""
}

Sample usage:

 

PUT /binMgr/Art2
{
  "binMgrDesc": "For QA use",
  "binMgrId": "Art2",
  "binMgrUrl": "http://localhost:8081/artifactory",
  "password": "password",
  "proxy_enabled": false,
  "user": "admin"
}


Response Codes:

200: BinMgr has been successfully updated
400: Path parameter is missing
400: Artifactory URL cannot contain localhost
401: Bad Credentials
500: Failed to obtain response


Get Artifactory

Description: Gets the details of the specified connected Artifactory instance
Security:  Requires a valid user
Usage: GET /binMgr/{id}

Sample usage:

 

GET /binMgr/###art12
{
  "binMgrUrl": "http://localhost:8081/artifactory",
  "binMgrId": "###art12",
  "binMgrDesc": "",
  "version": "4.x-SNAPSHOT",
  "proxy_enabled": false
}


Response Codes:

200: Artifactory model
400: Path parameter is missing
401: Bad Credentials
500: Failed to obtain response


Delete Artifactory Instance 

Description: Deletes an Artifactory instance configuration
Security:  Requires an admin user
Usage: POST /binMgr/delete
Consumes: application/json

 

{
  "binMgrDesc": "",
  "binMgrId": "",
  "binMgrUrl": "",
  "password": "",
  "proxy_enabled": <true | false>,
  "user": ""
}

Sample usage:

 

POST /binMgr/{id}
 
{
  "binMgrDesc": "For QA",
  "binMgrId": "arti2",
  "binMgrUrl": "http://localhost:8081/artifactory",
  "password": "password",
  "proxy_enabled": true,
  "user": "admin"
}


Response Codes:

200: BinMgr has been successfully updated
400: Path parameter is missing
400: Artifactory URL cannot contain localhost
401: Bad Credentials
500: Failed to obtain response


COMPONENTS

Create Component Mapping

Description: Creates a new mapping between a component's ID and its SHA2 checksum
Security:  Requires an admin user
Usage: POST /componentMapper
Consumes: application/json

{
  "componentId": "<component's identifier>",
  "blobs": ["<SHA2 checksum>"]	
}

Sample usage:

POST /componentMapper
{
	"componentId": "gav://ant:ant:1.6.5",
  	"blobs": ["49b4be297d4526ec17ea6773dde39721e1dda990d5263877df539315b9ea421d"]
}

 

Response Codes:

200: Component successfully added

400: Failed to add component mapping

409: Component ID already exists


Get Component Mapping

Description: Get's an object's SHA2 checksum by its component ID
Security:  Requires an admin user
Usage: GET /componentMapper/{componentId}
Produces: application/json

Sample usage:

GET /componentMapper/gav://ant:ant:1.6.5
{
	"componentId": "gav://ant:ant:1.6.5",
  	"blobs": ["49b4be297d4526ec17ea6773dde39721e1dda990d5263877df539315b9ea421d"]
}

 

Response codes:

200: Component mapping successful

400: Failed to get component mapping

401: Component id not found

500: Failed to obtain component mapping


Delete Component Mapping

Description: Deletes an object's SHA2 checksum to component ID mapping
Security:  Requires an admin user
Usage: DELETE /componentMapper/{componentId}
Produces: application/json

DELETE /componentMapper/gav://ant:ant:1.6.5


Response Codes:

200: component has been successfully deleted

400: Failed to delete component mapping


Add New Components

Description: Adds new components
Security:  Requires an admin user
Usage: POST /component

Consumes: application/json

{
  "components": [
    {
      "component": "",
      "created": "2006-01-02T15:04:05Z",
      "description": "",
      "downloads": 12,
      "licenses": [
        ""
      ],
      "modified": "2006-01-02T15:04:05Z",
      "name": "",
      "package_type": "",
      "sources": [
        {
          "name": "",
          "updated": "2006-01-02T15:04:05Z",
          "url": ""
        }
      ],
      "vcs_url": "",
      "versions": [
        {
          "downloads": 12,
          "files": [
            {
              "md5": "",
              "name": "",
              "sha1": "",
              "sha256": ""
            }
          ],
          "licenses": [
            ""
          ],
          "released": "2006-01-02T15:04:05Z",
          "version": ""
        }
      ],
      "website_url": ""
    }
  ]
}

 

Response Codes:

200: Shows details of an added component

400: Failed to obtain component

500: Failed to add component


Find Component by Name

Description: Search for a component by name - applicable only for components synced from the JFrog Global database to Xray 
Security:  Requires a valid user
Usage: GET /component/{name}
Produces: application/json
Sample usage: 

GET /component/Jinja2
 
{
  "component": "Jinja2",
  "package_type": "pip",
  "name": "Jinja2",
  "description": "A small but fast and easy to use stand-alone template engine written in pure python.",
  "website_url": "http://jinja.pocoo.org/",
  "downloads": 35536045,
  "created": "2008-06-09T16:50:19Z",
  "modified": "2016-12-30T06:03:21.705Z",
  "sources": [
    {
      "name": "pypi",
      "url": "https://pypi.python.org",
      "updated": "2016-12-30T06:03:21.678Z"
    }
  ],
  "versions": [
    {
      "version": "2.8.1",
      "released": "2016-12-29T13:16:20Z",
      "licenses": [
        "BSD"
      ],
      "files": [
        {
          "name": "Jinja2-2.8.1-py2.py3-none-any.whl",
          "sha256": "3997cf273f1424207c60d5895264f74483fce72702f15a7cd51a8551d43663ca",
          "sha1": "805e865181e6bce2f2f6f74f7b54bd913fc54b27",
          "md5": "7472b9df828747c2d44eb539558bbf7a"
        },
        {
          "name": "Jinja2-2.8.1.tar.gz",
          "sha256": "35341f3a97b46327b3ef1eb624aadea87a535b8f50863036e085e7c426ac5891",
          "sha1": "6baee2df662bf193bb3669c2c5b475da6083e2aa",
          "md5": "150a8f1c180272753cf46dd3cdd6decf"
        }
      ]
    }
  ]
}


Response Codes:

200: Component found

400: Failed to resolve component mapping

500: Failed to get component by name


Get Artifact Dependency Graph

Description: Get the complete dependency graph for an artifact
Security:  Requires a valid user
Usage: POST /dependencyGraph/artifact
Consumes: application/json

{
  "path": "<artifactory-name/repo-name/path>"
}

Produces: application/json

{
  "artifact":{
    "name": "<The name of the artifact who's graph we are obtaining>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Artifact's SHA256 checksum>",
    "sha1": "<Artifact's SHA1 checksum>",
    "component_id": "<The component ID>"
  },
  "components":[ 
    {
      "component_name":"<Dependency component name>",
      "component_id":"<Dependency Component ID>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "components":[<Next level dependencies of the dependency component>] 
    }]
}

Sample Usage:

POST /dependencyGraph/artifact
{
  "path": "/Artifactory/pnnl/goss/goss-core-client/0.1.7/goss-core-client-0.1.7-sources.jar"
}
 
{
  "artifact":{
    "name": "artifactory-pro.zip",
    "path": "art2/ext-release-local/",
    "pkg_type": "Generic",
    "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
    "sha1": "",
    "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
  },
  "components":[
    {
      "component_name":"some-component-1.1",
      "component_id":"pip://some-component:1.1",
      "package_type":"pip",
      "version":"1.1",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z",
      "components":[]
    },
    {
      "component_name":"some-component-1.2",
      "component_id":"pip://some-component:1.2",
      "package_type":"pip",
      "version":"1.2",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z",
      "components":[
        {
          "component_name":"Jinja2.7.2",
          "component_id":"pip://Jinja2:2.7.2",
          "package_type":"pip",
          "version":"2.7.2",
          "created":"2008-06-09T16:50:19Z",
          "modified":"2015-07-26T17:49:47Z",
          "components":[]
        }
      ]
    }
  ]
}

Response Codes:
200: Success
400: Artifact '<PATH>' doesn't exist or isn't indexed in Xray
401: Bad credentials
415: Failed to parse request


Compare Artifacts

Description: Compares two artifacts and produces the difference between them
Security:  Requires a valid user
Usage: POST /dependencyGraph/artifactDelta
Consumes: application/json

{
 "source_artifact_path":"<artifactory/repo/path>",
 "target_artifact_path":"<artifactory/repo/path>"
}

Produces:

{
  "source_artifact":{
    "name": "<The name of the source artifact we are comparing>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Artifact's SHA256 checksum>",
    "sha1": "<Artifact's SHA1 checksum>",
  },
  "target_artifact":{
    "name": "<The name of the target artifact we are comparing>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Artifact's SHA256 checksum>",
    "sha1": "<Artifact's SHA1 checksum>",
  },
  "removed":[
    {
      "component_name":"<Component name only found in source artifact>",
      "component_id":"<Dependency Component ID only found in source artifact>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>"
    }
  ],
  "added":[
    {
      "component_name":"<Component name only found in target artifact>",
      "component_id":"<Dependency Component ID only found in target artifact>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    }
  ],
 "unchanged":[
    {
      "component_name":"<Component name only found in both artifacts>",
      "component_id":"<Dependency Component ID only found in both artifacts>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    }
  ]
}

Sample Usage:

POST /dependencyGraph/artifactDelta
{
 "source_artifact_path":"/pnnl/goss/goss-core-client/0.1.7/goss-core-client-0.1.7-sources.jar",
 "target_artifact_path":"/pnnl/goss/goss-core-client/0.1.8/goss-core-client-0.1.8-sources.jar",
}
 
{
  "source_artifact":{
    "name": "artifactory-pro.zip",
    "path": "art2/ext-release-local/",
    "pkg_type": "Generic",
    "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
    "sha1": ""
  },
  "target_artifact":{
    "name": "artifactory-pro.zip",
    "path": "art2/ext-release-local/",
    "pkg_type": "Generic",
    "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
    "sha1": ""
  },
  "removed":[
    {
      "component_name":"some-component-1.1",
      "component_id":"pip://some-component:1.1",
      "package_type":"pip",
      "version":"1.1",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ],
  "added":[
    {
      "component_name":"Jinja2.7.2",
      "component_id":"pip://Jinja2:2.7.2",
      "package_type":"pip",
      "version":"2.7.2",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ],
 "unchanged":[
    {
      "component_name":"Apache1.4",
      "component_id":"gav://apache:1.4",
      "package_type":"maven",
      "version":"1.4",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ]
}

Response Codes:
200: Success
400: Artifact '<PATH>' doesn't exist or isn't indexed in Xray
401: Bad Credentials
415: Failed to parse request


Get Build Dependency Graph

Description: Get the complete dependency graph for a build
Security:  Requires a valid user
Usage: POST /dependencyGraph/build
Consumes: application/json

{
 "artifactory_id":"<Artifactory instance name>",
 "build_name":"<Build name>",
 "build_number":"<Build number>"
}

Produces: application/json

{
  "build":{
    "name": "<The name of the build who's graph we are obtaining>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Artifact's SHA256 checksum>",
    "component_id": "<The component ID>"
  },
  "components":[ 
    {
      "component_name":"<Dependency component name>",
      "component_id":"<Dependency Component ID>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "components":[] 
    }]
}

Sample Usage:

POST /dependencyGraph/build
{
 "artifactory_instance":"myInstance",
 "build_name":"someBuild",
 "build_number":"someNumber"
}
 
{
  "build": {
      "name": "my-build",
      "path": "art2/ext-release-local/",
      "pkg_type": "Generic",
      "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
      "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
    },
  "components":[
    {
      "component_name":"some-component-1.1",
      "component_id":"pip://some-component:1.1",
      "package_type":"pip",
      "version":"1.1",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z",
      "components":[]
    },
    {
      "component_name":"some-component-1.2",
      "component_id":"pip://some-component:1.2",
      "package_type":"pip",
      "version":"1.2",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z",
      "components":[
        {
          "component_name":"Jinja2.7.2",
          "component_id":"pip://Jinja2:2.7.2",
          "package_type":"pip",
          "version":"2.7.2",
          "created":"2008-06-09T16:50:19Z",
          "modified":"2015-07-26T17:49:47Z",
          "components":[]
        }
      ]
    }
  ]
}

Response Codes:
200: Success
400: Build '<PATH>' doesn't exist or isn't indexed in Xray
400: Missing build name
400: Missing build number
400: Missing Artifactory ID
401: Bad credentials
415: Failed to parse request 


Compare Builds

Description: Compares two builds and produces the difference between them
Security:  Requires a valid user
Usage: POST /dependencyGraph/buildDelta
Consumes: application/json

{
 "source_artifactory_id":"<First instance name>",
 "source_build_name":"<First build name>",
 "source_build_number":"<First build number>",
 "target_artifactory_id":"<Second instance name>",
 "target_build_name":"<Second build name>",
 "target_build_number":"<Second build number>"
}

Produces: application/json

{
  "source_build":{
    "name": "<The name of the source build we are comparing>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Build's SHA256 checksum>",
    "component_id": "<Build's component ID>",
  },
  "target_build":{
    "name": "<The name of the target build we are comparing>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Build's SHA256 checksum>",
    "component_id": "<Build's component ID>",
  },
  "removed":[
    {
      "component_name":"<Component name only found in source build>",
      "component_id":"<Dependency Component ID only found in source build>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>"
    }
  ],
  "added":[
    {
      "component_name":"<Component name only found in target build>",
      "component_id":"<Dependency Component ID only found in target build>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    }
  ],
 "unchanged":[
    {
      "component_name":"<Component name only found in both builds>",
      "component_id":"<Dependency Component ID only found in both builds>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    }
  ]
}

Sample Usage:

POST /dependencyGraph/buildDelta
{
 "origin_build_artifactory_instance":"my-instance",
 "origin_build_name":"someOriginBuild",
 "origin_build_number":"111",
 "target_build_artifactory_instance":"my-instance",
 "target_build_name":"someTargetBuild",
 "target_build_number":"222",
}
 
{
  "source_build":{
    "name": "my-build",
      "path": "art2/ext-release-local/",
      "pkg_type": "Generic",
      "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
      "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
  },
  "target_build":{
    "name": "my-build",
      "path": "art2/ext-release-local/",
      "pkg_type": "Generic",
      "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
      "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
  },
  " removed":[
    {
      "component_name":"some-component-1.1",
      "component_id":"pip://some-component:1.1",
      "package_type":"pip",
      "version":"1.1",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ],
  "added":[
    {
      "component_name":"Jinja2.7.2",
      "component_id":"pip://Jinja2:2.7.2",
      "package_type":"pip",
      "version":"2.7.2",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ],
 "unchanged":[
    {
      "component_name":"Apache1.4",
      "component_id":"gav://apache:1.4",
      "package_type":"maven",
      "version":"1.4",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ]
}

Response Codes:
200: Success
400: The build with the provided identifier doesn't exist or isn't indexed in Xray
401: Bad credentials
415: Failed to parse request


VULNERABILITIES

Create a New Issue Event

Description: Enables an Issue Vendor to Create a New Issue Event in Xray
Security:  Requires a valid user
Usage: POST /events
Consumes: application/json

{
  "components": [
    {
      "component_id": "",
      "properties": [
        ""
      ]
    }
  ],
  "created": "2006-01-02T15:04:05Z",
  "description": "",
  "id": "",
  "modified": "2006-01-02T15:04:05Z",
  "properties": [
    "interface"
  ],
  "provider": "",
  "severity": "",
  "source_id": "",
  "summary": "",
  "type": "",
  "updated": "2006-01-02T15:04:05Z",
  "url": ""
}

 

Response codes:

200: Vulnerability data added successfully

500: Failed to add vulnerability data


Gets Single Issue Event

Description: Retrieves one vulnerability issue created by a vendor
Security:  Requires a valid user
Usage: GET /events/{componentId}
Produces: application/json

Response codes:

200: Vulnerability issue retrieved successfully

404: Failed to get vulnerability issue

500: Vulnerability issue not found


Allows an issue vendor to update an issue event

Description: Enables an Issue Vendor to Create a New Issue Event in Xray
Security:  Requires a valid user
Usage: PUT /events

Consumes: application/json

{
  "components": [
    {
      "component_id": "",
      "properties": [
        ""
      ]
    }
  ],
  "created": "2006-01-02T15:04:05Z",
  "description": "",
  "id": "",
  "modified": "2006-01-02T15:04:05Z",
  "properties": [
    "interface"
  ],
  "provider": "",
  "severity": "",
  "source_id": "",
  "summary": "",
  "type": "",
  "updated": "2006-01-02T15:04:05Z",
  "url": ""
}

 

Response Codes:

200: Vulnerability has been updated successfully

500: Failed to update vulnerability

 


INDEX

Index artifact

Description: Indexes an artifact
Security:  Requires an admin user
Usage: POST /index
Consumes: application/json

 {
  "archivePath": "",
  "artifactoryId": "",
  "buildName": "",
  "buildNumber": "",
  "checksums": {
    "md5": "",
    "sha1": "",
    "sha256": ""
  },
  "componentId": "",
  "created": 123,
  "downloadUrl": "",
  "downloadedArchive": [
    {
      "ArchiveName": "",
      "DownloadLink": "",
      "SavedFilePath": "",
      "Sha": ""
    }
  ],
  "eventTime": 123,
  "eventType": "",
  "existArchive": [
    {
      "ArchiveName": "",
      "DownloadLink": "",
      "SavedFilePath": "",
      "Sha": ""
    }
  ],
  "messageId": "",
  "origEventType": "",
  "path": "",
  "repoKey": "",
  "sourcePath": "",
  "sourceRepoKey": ""
}

 

Response Codes:

200: Index event successfully sent to queue

415: Unsupported media type

500: Failed to update event states for message


INTEGRATION

Get Integration Configuration

Description: Retrieves integrations configured into the system
Security:  Requires an admin user
Usage: GET /integration

Produces: application/json

Sample usage:

GET /integration
 
 [
  {
    "vendor": "whitesource",
    "api_key": "4a547ccd-fdf0-4ac4-8ec2-259ce91c1633",
    "enabled": <true|false>,
    "context": "project_id",
    "url": "https://saas.whitesourcesoftware.com/xray",
    "description": "WhiteSource provides a simple yet powerful open source security and licenses management solution. More details at http://www.whitesourcesoftware.com.",
    "test_url": "https://saas.whitesourcesoftware.com/xray/api/checkauth"
  }
]

 

Response Codes:

200: Integration data retrieved successfully

500: Failed to retrieve integration data


Add Integration Configuration

Description: Add an integration configuration
Security:  Requires an admin user
Usage: POST /integration

Consumes: application/json

 

 {
  "vendor": ""
  "api_key": "",
  "enabled": <true|false>,
  "context": "",
  "url": "",
  "description": "",
  "test_url": ""
}

 

Sample usage:

POST /integration
 
{
  "vendor": "whitesource",
  "api_key": "12345",
  "enabled": true,
  "context": "project_id",
  "url": "https://saas.whitesourcesoftware.com/xray",
  "description": "WhiteSource provides a simple yet powerful open source security and licenses management solution. More details at http://www.whitesourcesoftware.com.",
  "test_url": "https://saas.whitesourcesoftware.com/xray/api/checkauth"
}

 

Response Codes:

200: Integration data successfully added

500: Failed to register integration data


Update Integration Configuration

Description: Updates the integration configuration
Security:  Requires an admin user
Usage: PUT /integration/{name}
Consumes: application/json

 

 {
  "vendor": "",
  "api_key": "",
  "enabled": <true|false>,
  "context": "",
  "url": "",
  "description": "",
  "test_url": ""
}

 

Response Codes:

200: Integration data successfully Updated

500: Failed to register integration data


Delete Integration Configuration

Description: Delete integration configuration
Security:  Requires an admin user
Usage: DELETE /integration/{name}
Produces: application/json

Sample usage:

 DELETE /integration/whitesource

 

Response Codes:

200: Integration deleted successfully

400: Vendor name is missing

500: Failed to delete integration


MONITORING

Get System Monitoring Status

Description: Gets system monitoring status
Security:  Requires a valid user
Usage: GET /monitor
Produces: application/json

Sample usage:
GET /monitor
 
{
 "problems": [
   {
     "severity": "warning",
     "services": [
       "analysis",
       "event",
       "indexer",
       "xray_server"
     ],
     "problem": "No connection to Artifactory instance ###art12"
   }
 ]
}

 

Response Codes:

200: System monitoring status was sent

500: Failed to marshal object to json


LICENSE REPORTS

Get License Report

Description: Gets a report describing the distribution and compliance status of licenses in all indexed components
Security:  Requires a valid user
Usage: GET /licensesReport
Produces: application/json

Sample usage:

GET /licensesReport
{
  "distribution": {
    "Apache-2.0": 24,
    "MIT": 10,
    "Other": 1,
    "Unknown": 333
  },
  "compliance": {
    "banned": 25,
    "unknown": 333,
    "valid": 10
  },
  "lastUpdate": "2017-01-01T12:20:49.024397147Z"
}

 

Response Codes:

200: Successfully obtained license report


Get License Report Components

Description: Get license report.  either `license` or `compliance` query parameter are required
Security:  Requires a valid user
Usage: GET /licensesReport/components?[license=<license(BSD,  GPL etc.)> | compliance=<unknown | valid | banned>]&direction=<asc | desc>&num_of_rows=<rows>&order_by=<id | licenses>&page_num=<page to view>
Produces: application/json
Sample usage:

 

GET /licensesReport/components?compliance=valid&token=12345&direction=asc&num_of_rows=20&order_by=id&page_num=1
 
{
  "data": [
    {
      "component_id": "npm://backbone.datastore:1.0.3",
      "component_name": "backbone.datastore:1.0.3",
      "pkg_type": "Npm",
      "is_root": false,
      "licenses": [
        "MIT"
      ],
      "watches": [
        "MIT-allowed"
      ]
    },
	...
}
 

 

Response Codes:

200: Successfully obtained license report components

400: Failed to get report components - check pagination query parameters.

500: Failed to obtain report components


Run License Report Generation

Description: Generate synchronized licensed report and wait for results
Security:  Requires a valid user
Usage: GET /licensesReport/generate
Produces: application/json 

Sample usage:

{
  "info": "License report was regenerated"
}

 

Response Codes:

200: License report was regenerated

500: Failed to regenerate license report


 

SECURITY REPORTS

Generate Synchronized Security Report

Description:  Generate synchronized security report and wait for results
Security:  Requires a valid user
Usage: GET /securityReport/generate
Produces: application/json

 

 

{
  "info": "security report was regenerated"
}

 

Response Codes:

200: Security report was regenerated

500: Failed to regenerate security report


Get Security Report

Description: Get the security report
Security:  Requires a valid user
Usage: GET /securityReport
Produces: application/json

{
  "lastUpdate": "Time",
  "recent_components": [
    <int>
  ],
  "recent_vulnerabilities": [
    <int>
  ],
  "top_artifacts": [
    {
      "indexed": "Time",
      "name": "",
      "package_type": "",
      "path": "",
      "vulnerabilities": [
        {
          "id": {},
          "summary": ""
        }
      ]
    }
  ],
  "top_vulnerabilities": [
    {
      "affected_components": [
        {
          "id": "",
          "impacted_paths": [
            ""
          ]
        }
      ],
      "created": "Time",
      "description": "",
      "properties": [
        "interface"
      ],
      "severity": "",
      "summary": ""
    }
  ]
}

 

Sample usage:

GET /securityReport
 
{
  "recent_vulnerabilities": {
    "2016-12-04": 0,
    "2016-12-11": 0,
    "2016-12-18": 0,
    "2016-12-25": 0,
    "2017-01-01": 3
  },
  "recent_components": {
    "2016-12-04": 0,
    "2016-12-11": 0,
    "2016-12-18": 0,
    "2016-12-25": 46,
    "2017-01-01": 0
  },
  "top_vulnerabilities": [
    {
      "summary": "CWE-20 Improper Input Validation",
      "description": "The MultipartStream class in Apache Commons Fileupload before 1.3.2, as used in Apache Tomcat 7.x before 7.0.70, 8.x before 8.0.36, 8.5.x before 8.5.3, and 9.x before 9.0.0.M7 and other products, allows remote attackers to cause a denial of service (CPU consumption) via a long boundary string.",
      "severity": "Critical",
      "properties": {
        "cve": "CVE-2016-3092",
        "cvss_v2": "7.8",
        "description": "The MultipartStream class in Apache Commons Fileupload before 1.3.2, as used in Apache Tomcat 7.x before 7.0.70, 8.x before 8.0.36, 8.5.x before 8.5.3, and 9.x before 9.0.0.M7 and other products, allows remote attackers to cause a denial of service (CPU consumption) via a long boundary string.",
        "publish_date": "2016-07-04T18:59:04.000Z",
        "references": [
          "http://svn.apache.org/viewvc?view=revision&revision=1743480",
          "http://svn.apache.org/viewvc?view=revision&revision=1743722",

	...
        ],
        "summary": "CWE-20 Improper Input Validation"
      },
      "created": "2016-07-04T18:59:04Z",
      "affected_components": [
        {
          "id": "gav://org.apache.tomcat:tomcat-servlet-api:8.0.32"
        },
        {
          "id": "gav://org.apache.tomcat:tomcat-api:8.0.32"
        },

	...
	}
	],
  "top_artifacts": [
    {
      "name": "artifactory-pro-war-4.x-20160616.132515-1.war",
      "path": "/org/artifactory2/pro/artifactory-pro-war/4.x-SNAPSHOT/",
      "package_type": "Maven",
      "indexed": "2016-12-07T14:13:14Z",
      "vulnerabilities": [
        {
          "id": "584818fcaee4940008425415",
          "summary": "The authenticated-encryption feature in the symmetric-encryption implementation in the OWASP Enterprise Security API (ESAPI) for Java 2.x before 2.1.0 does not properly resist tampering with serialized ciphertext"
        },
        {
          "id": "5820903652a576000835b360",
          "summary": "CWE-399 Resource Management Errors"
        },

	...
	}
	],
  "lastUpdate": "2017-01-01T18:01:08.456580152Z"
}

 

Response Codes:

200: Security report successful


Get Recent Vulnerabilities 

Description: Get recent vulnerabilities for a given week, for the security report
Security:  Requires a valid user
Usage: GET /securityReport/recentVulnerabilities?time=<End of week date in format: YYYY-MM-DD>&token=<authentication token>&direction=<asc | desc>&num_of_rows=<rows to display>&page_num=<page to view>
Produces: application/json 

{
  "data": "interface",
  "total_count": 10
}

Sample Usage: 

 

GET /securityReport/recentVulnerabilities?time=2016-12-31&token=12345&&direction=asc&num_of_rows=20&page_num=1
 
{
  "data": null,
  "total_count": 0
}

 

Response Codes:

200: Successfully obtained all the vulnerabilities for a given week

400: Failed to get recent vulnerabilities - check pagination query parameters

400: Failed to get recent vulnerabilities - no time period was specified


Get Recent Components 

Description: Get recent components for all security report in given week period
Security:  Requires a valid user
Usage: GET /securityReport/recentComponents?time=<End of week date in format: YYYY-MM-DD>&token=<authentication token>&direction=<asc | desc>&num_of_rows=<rows to display>&page_num=<page to view>

Produces: application/json

{
  "data": "interface",
  "total_count": 11
}

 

Sample usage: 

GET /securityReport/recentComponents?time=2016-12-31&token=12345&&direction=asc&num_of_rows=20&page_num=1
 
{
  "data": null,
  "total_count": 0
}

 

Response Codes:

200: Successfully obtained recent components

400: Failed to get recent components - check pagination query parameters.

400: Failed to get recent components - no time period was specified


SUMMARY

Build Summary

Description: Provides details about any build specified by build identifier (name + number)
Security:  Requires a valid user
Usage: GET /summary/build?build_name=<build name>&build_number=<build number>
Produces: application/json

{
  "artifacts": [
    {
      "general": {
        "component_id": "",
        "name": "",
        "path": "",
        "pkg_type": "",
        "sha256": ""
      },
      "issues": [
        {
          "created": "",
          "description": "",
          "impact_path": [
            {}
          ],
          "issue_type": "",
          "provider": "",
          "severity": "",
          "summary": ""
        }
      ],
      "licenses": [
        {
          "components": [
            "sets.SetInterface"
          ],
          "full_name": "",
          "more_info_url": [
            ""
          ],
          "name": ""
        }
      ]
    }
  ],
  "errors": [
    {
      "error": "",
      "identifier": ""
    }
  ]
}

Response Codes: 

200: Obtained artifact build summary

400: Missing build name or build number


Artifact Summary

Description: Provides details about any artifact specified by path identifiers or checksum
Security: Requires a valid user
Usage: POST /summary/artifact
Consumes: application/json

{
  "checksums": [
    ""
  ],
  "paths": [
    ""
  ]
}

Produces: application/json

{
  "artifacts": [
    {
      "general": {
        "component_id": "",
        "name": "",
        "path": "",
        "pkg_type": "",
        "sha256": ""
      },
      "issues": [
        {
          "created": "",
          "description": "",
          "impact_path": [
            {}
          ],
          "issue_type": "",
          "provider": "",
          "severity": "",
          "summary": ""
        }
      ],
      "licenses": [
        {
          "components": [
            "sets.SetInterface"
          ],
          "full_name": "",
          "more_info_url": [
            ""
          ],
          "name": ""
        }
      ]
    }
  ],
  "errors": [
    {
      "error": "",
      "identifier": ""
    }
  ]
}

Sample Usage:

POST /summary/artifact
{
    "checksums":["d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2"]
}
  
Response
{
  artifacts: [
    "general": {
      "name": "artifactory-pro.zip",
      "path": "art2/ext-release-local/",
      "pkg_type": "Generic",
      "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
      "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
    },
    "issues":[
      {
        "summary":"FileSystemBytecodeCache in Jinja2 2.7.2 does not properly create temporary directories",
        "description":"this is the description of the issue",
        "issue_type":"security",
        "severity":"Major",
        "provider":"JFrog",
        "created":"2016-10-26T11:15:51.17Z",
        "impact_path": [
          "xray-artifactory/maven-1000/com/atlassian/aui/auiplugin/0.0.5-9-0-snapshot-035-do-not-use/Jinja2-2.7.2"
        ]
      }
    ],
    "licenses":[
      {
        "name":"MIT",
        "full_name":"The MIT License",
        "more_info_url":"https://opensource.org/licenses/MIT",
        "components":[
          "some-component-1",
          "some-component-2",
          "some-component-3"
        ]
      },
      {
        "name":"AGPL-3.0",
        "full_name":"GNU AFFERO GENERAL PUBLIC LICENSE, Version 3",
        "more_info_url":"https://opensource.org/licenses/AGPL-3.0",
        "components":[
          "some-component-4",
          "some-component-5"
        ]
      },
      {
        "name":"unknown",
        "components":[
          "some-component-6",
          "some-component-7"
        ]
      }
  ],
  errors: [
    {
      identifier: "4e39f19212597312ee02db873847bcb12c17cc639898bd2fd9b6a4aff16690e5",
      error: "Artifact doesn't exist or not indexed in Xray"
    }
  ]
}

Response Codes:

200: Obtained artifact summary

415: Failed to parse JSON


SYSTEM

Ping Request

Description: Sends a ping request
Security: Requires a valid user
Usage: GET /system/ping
Produces: application/json
Sample usage:

GET /system/ping
{"status":"pong"}

Response Codes:

200: Ping successful


External Ping Request

Description: Sends a ping request to external sources
Security: Requires a valid user
Usage: GET /system/external/ping

Response Codes:
200: Ping successful to external source
404: Page not found


Get Version

Description: Gets the Xray version and revision you are running
Security: Requires a valid user
Usage: GET /system/version
Produces: application/json

{
    "xray_version":"<version number>",
    "xray_revision":"<revision number>"
}

Sample Usage:

GET /system/version
  
{
    "xray_version":"1.4",
    "xray_revision":"b3034"
}

 

Response Codes:

200: Got version info successfully