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

Skip to end of metadata
Go to start of metadata

Overview

Mission Control exposes a rich REST API to allow fully automated management of Artifactory and Xray services under your control.

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

Version

Mission Control REST API is currently in Version 3 and is a major upgrade which includes significant changes from the previous version.

If you are still using Version 2 of the REST API, please refer to Mission Control REST API v2, however note that this has been deprecated. 

We strongly recommend that you upgrade your scripts to the latest API version, and to facilitate the required modifications, please refer to Version Mapping below. 

 

Authentication

All Mission Control REST API endpoints require basic authentication using your username and password except for the System Health Check.

Usage

Mission Control REST API can be invoked in any of the standard ways for a REST API. The following section describes how to use the Mission Control REST API using cURL as an example.

Using and configuring cURL 

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

Example - Create Site

The example below demonstrates how to invoke the create user REST API.

  • You have MissionControl  running on your local system, on port 8080

  • You wish to create a site called "us-west" containing both an Artifactory and Xray service

  • You created a file with the site's parameters called createsite.json

To use the file to create a new user, you would use the following command:

Using cURL with the REST API
$ curl 'http://localhost:8080/api/v3/sites' -i -u 'admin:password' -X POST -H 'Content-Type: application/json; charset=UTF-8' -T createsite.json
The file createsite.json will contain the following :
{
    "name": "us-west",
    "description": "US West coast site",
    "city": {
        "name": "Sunnyvale",
        "country_code": "US",
        "latitude": 37.368830,
        "longitude": -122.036350
    },
    "services": ["arti-west", "xray-west"]
}

SYSTEM 

System Health Check

Description: Get an indication if Mission Control is running or not
Since: 2.0
Usage: GET /api/v3/ping
Example:

GET /api/v3/ping
 
true

SITES

These are the relevant fields when configuring sites:

FieldTypeOptionalDescription

name

StringfalseSite's name
descriptionStringtrueSite's description
cityObjectfalseSite's city
city.nameStringtrueCity's name
city.country_codeStringtrueCity's country code
city.longitudeNumberfalseCity's longitude
city.latitudeNumberfalseCity's latitude
servicesArraytrueNames of services

Create Site 

Description: Create a new site.

Since: 2.0
Security: Requires an admin user
Usage: POST /api/v3/sites

Return codes:

201 - No Content
400 -  Couldn't find service(s) with following name(s):, '<Service name>', '<Service name>'

409 -  Name '<Site name>' already exists.

Consumes: application/json

 

{
    "name" : "<Site name>",
    "description" : "<Site description>",
    "city" : {
	  "name" : "<City name>",
      "country_code" : "<Country code>",
      "latitude" : <City lat coordinate>,
      "longitude" : <City lon coordinate>
     },
	 "services" : [  "<Service name>" ] 
} 

 

Example:
In this example, a new Sunnyvale site is created and services "arti-west" and "xray-west" are associated with the new site. If the services exist, 201 Created will be returned. 

$ curl 'http://localhost:8080/api/v3/sites' -i -u 'admin:password' -X POST -H 'Content-Type: application/json; charset=UTF-8' -T createsite.json

 

 

createsite.json
{
    "name": "us-west",
    "description": "US West coast site",
    "city": {
        "name": "Sunnyvale",
        "country_code": "US",
        "latitude": 37.368830,
        "longitude": -122.036350
    },
    "services": ["arti-west", "xray-west"]
}
 

 


Update Site  

Description: Updates an exiting site by name.

Since: since 2.0
Security: Requires an admin user
Usage: PUT /api/v3/sites/{name}

Return codes:

204 - No Content
409 -  The entity 'Site' with identifier '<Site-name>' was not found

Consumes: application/json

 

{
    "name" : "<Updated site name>",
    "description" : "<Updated site description>",
    "city" : {
	  "name" : "<Updated city name>",
      "country_code" : "<Updated country code>",
      "latitude" : <Updated city lat coordinate>,
      "longitude" : <Updated city lon coordinate>
     		    },
    "services" : [ {
    	"name" : "<Service name>",
		"type" : "<ARTIFACTORY | XRAY>"
	}]
} 

 

 

Example :

In this example, an existing site named Argentina is being updated to Mexico Data Center with appropriate attributes. If the site 'Argentina' exists, 204 No Content will be returned

$ curl -XPUT 'http://localhost:8080/api/v3/sites/Argentina' -i -u 'admin:password' -H 'Content-Type: application/json; charset=UTF-8' -T updatesite.json
updatesite.json
{
    "name" : "Mexico Data Center",
    "description" : "Updated site description",
    "city" : {
		"name" : "Mexico City",
      	"country_code" : "MX",
      	"latitude" : 19.428470,
      	"longitude" : -99.127660
	}
}

Partial Update Site By Name

Description: Updates a site without updating the attributes.
Since: 2.1

Security: Requires an admin user
Usage: PUT /api/v3/services/{name}

Return codes:

204 - No Content
Consumes: application/json

 

PATCH /api/v3/sites/{name} 		

Example:

PATCH /api/v3/sites/Site%20name HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: localhost:8080
Content-Length: 119
 
{
    "name" : "Updated site name",
    "description" : "Updated site description",
    "services" : [ "Artifactory name" ]
} 

    HTTP/1.1 204 No Content
 

Example:

$ curl 'http://localhost:8080/api/v3/sites/Site%20name' -i -u 'admin:password' -X
PATCH -H 'Content-Type: application/json; charset=UTF-8' -d '{
          "name" : "Updated site name",
          "description" : "Updated site description",
          "services" : [ "Artifactory name" ]
}' 	

 


Get Site 

Description: Gets a site by name

Since: 2.0
Security: Requires an admin user
Usage: GET /api/v3/sites/{name}

Return codes:

200 - Success
409 -  The entity 'Site' with identifier '{name}' was not found"

Produces: application/json

 

{
    "name" : "<Site name>",
    "description" : "<Site description>",
    "city" : {
	  "name" : "<City name>",
      "country_code" : "CODE",
      "latitude" : <City lat coordinate>,
      "longitude" : <City lon coordinate>
     		    },
    "services" : [ {

    "name" : "<Service name>",
	"type" : "<ARTIFACTORY | XRAY>"
	}]
} 

 

Example:

In this example, information regarding Site named 'China' is being retrieved. If site 'China' exists 200 Success will be returned 

$ curl -XGET 'http://localhost:8080/api/v3/sites/China' -uadmin:password 

 

 

example output
{
    "name": "Beijing",
    "description": "Beijing Data Center",
    "city": {
        "name": "Beijing",
        "country_code": "CN",
        "latitude": 39.907500,
        "longitude": 116.397230
    },
    "services": [
        {
            "name": "arti-beijing",
            "type": "ARTIFACTORY"
        }
    ]
}
200 Success

Get Site List

Description: Gets a list of all sites

Since: 2.0
Security: Requires an admin user
Usage: GET /api/v3/sites/

Return codes:

200 - Success
409 -  The entity 'Site' with identifier '<Site-name>' was not found

Produces: application/json

 

[{
    "name" : "<Site name>",
    "description" : "<Site description>",
    "city" : {
	  "name" : "<City name>",
      "country_code" : "CODE",
      "latitude" : <City lat coordinate>,
      "longitude" : <City lon coordinate>
     		    },
    "services" : [ {

    "name" : "<Service name>",
	"type" : "<ARTIFACTORY | XRAY>"
	}]
}]

 

Example:

$ curl -XGET 'http://localhost:8080/api/v3/sites' -uadmin:password 

 

 

example output
[
    {
        "name": "China",
        "description": "",
        "city": {
            "name": "Shanghai",
            "country_code": "CN",
            "latitude": 31.22222,
            "longitude": 121.45806
        },
        "services": [
            {
                "name": "China",
                "type": "ARTIFACTORY"
            }
        ]
    },
    {
        "name": "Argentina",
        "description": "",
        "city": {
            "name": "Buenos Aires",
            "country_code": "AR",
            "latitude": -34.61315,
            "longitude": -58.37723
        },
        "services": [
            {
                "name": "Source Local",
                "type": "ARTIFACTORY"
            }
        ]
    }
]
 
200 Success


Delete Site

Description: Delete a site

Since: 2.0
Security: Requires an admin user
Usage: DELETE /api/v3/sites/{name}
Return codes:

200 - Success
409 - Cannot delete site {name}, it has non-empty service(s): {name of the service}

Example:

$ curl -XDELETE 'http://localhost:8080/api/v3/sites/China' -uadmin:password  -H "Content-Type: application/json"

 



SERVICES 

Create Service 

Description: Creates a new service.

Since: 2.0
Security: Requires an admin user
Usage: POST /api/v3/services

Return codes:

201 - Created
409 -  Failed to connect to the service. Please verify that the service information provided is correct

Consumes: application/json

 

{			
	"name" : "<Service name>",
    "description" : "<Service description>",
    "url" : "<Service URL>",
    "username" : "<Service admin username>",
    "password" : "<Service admin password>",
    "type" : "<ARTIFACTORY | XRAY>"
} 

 

Example:

$ curl 'http://localhost:8080/api/v3/services' -i -u 'admin:password' -X POST -H 'Content-Type: application/json; charset=UTF-8' -T createservice.json

 

 

createservice.json
{
    "name" : "dev-west",
    "description" : "Artifactory serving development in West region",
    "url" : "https://artifactory-west.acme.com/artifactory",
    "username" : "admin",
    "password" : "password",
    "type" : "ARTIFACTORY"  
}
 
201 Created

 

Update Service

Description: Updates a service 

Since: 2.0
Security: Requires an admin user
Usage: PUT /api/v3/services/{name}

Return codes:

204 - No Content
409 -  Url <Service-url> already exists

Consumes: application/json

 

{			
	"name" : "<Service name>",
    "description" : "<Service description>",
    "url" : "<Service URL>",
    "username" : "<Service admin username>",
    "password" : "<Service admin password>"
}  

 

 Example:

$ curl 'http://localhost:8080/api/v3/services/dev-west' -i -u 'admin:password' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -T updateservice.json

 

 

updateservice.json
{
    "name" : "dev-east",
    "description" : "Artifactory serving development in East region",
    "url" : "https://artifactory-east.acme.com/artifactory",
    "username" : "admin",
    "password" : "password"  
}
 
204 No Content

 


Get Service List

Description: Get a list of all services

Since: 2.0
Security: Requires an admin user
Usage: GET /api/v3/services/
Produces: application/json

Example:

$ curl -XGET 'http://localhost:8080/api/v3/services' -uadmin:password 

 

 

example output
[
    {
        "name": "Argentina",
	    "description" : "Artifactory serving development in Argentina",
        "url": "http://10.0.0.8:8082/artifactory",
        "type": "ARTIFACTORY"
    },
    {
        "name": "China",
	    "description" : "Artifactory serving development in China",
        "url": "http://10.0.0.8:8081/artifactory",
        "type": "ARTIFACTORY"
    }
]
 
200 Success

Delete Service

Description: Deletes a service

Since: 2.0
Security: Requires an admin user
Usage: DELETE /api/v3/services/{name}
Return codes:

200 - Success

Example:

$ curl -XDELETE 'http://localhost:8080/api/v3/services/Argentina' -uadmin:password  -H "Content-Type: application/json"

 


Get Repository List

Description: Gets the list of repositories in the specified Artifactory service

Since: 2.0
Security: Requires an admin user
Usage: GET api/v3/services/artifactory/{name}/repositories
 
Return codes:

200 - Success

 
409 - Could not find Artifactory instance with name <Service-name>
Consumes: application/json

Example:

$ curl -XGET 'http://localhost:8080/api/v3/services/artifactory/{name}/repositories' -uadmin:password 
example output
[
    {
        "repository_key": "bower-local",
        "description": "",
        "type": "local",
        "package_type": "bower"
    },
    {
        "repository_key": "generic-local",
        "description": "",
        "type": "local",
        "package_type": "generic"
    },
    {
        "repository_key": "libs-release-local",
        "description": "",
        "type": "local",
        "package_type": "maven"
    },

...
 
    {
        "repository_key": "npm",
        "description": "",
        "type": "virtual",
        "package_type": "npm"
    }
]

 


MONITORING

Get Services Status

Description: Get status of all services
Since: 2.0
Usage: GET /api/v3/services/monitoring/status

Return codes:

200 - Success

Produces: application/json

[ 
	{ 
		"service_name": "<Service name>", 
		"up_time_in_sec": <Time in seconds that the service has been up>, 
		"service_state": "< ONLINE | OFFLINE >" 
	}
]

 

Example:

 

$ curl -XGET 'http://localhost:8080/api/v3/services/monitoring/status' -uadmin:password

 

 

example output
[ 
	{ 
		"service_name": "China", 
		"up_time_in_sec": 29282, 
		"service_state": "ONLINE" 
	}, 
	{ 
		"service_name": "Argentina", 
		"up_time_in_sec": 131, 
		"service_state": "ONLINE" 
	} 
]
 
200 Success

Get Service Status

Description: Get status of the specified service

Since: 2.0
Usage: GET /api/v3/services/{name}/monitoring/status
Return codes:

200 - Success

409 - Could not find service with name <Service-name>
Produces: application/json

 

{ 
	"service_name": "<Service name>", 
	"up_time_in_sec": <Time in seconds that the service has been up>, 
	"service_state": "< ONLINE | OFFLINE >"
}

 

Example:

 

$ curl -XGET 'http://localhost:8080/api/v3/services/China/monitoring/status' -uadmin:password

 

 

example output
{ 
	"service_name": "China", 
	"up_time_in_sec": 46182, 
	"service_state": "ONLINE" 
}
200 Success

 

DISASTER RECOVERY

Create DR Pair 

Description: Matches up a Master and Target Artifactory service as a DR pair. 

Since: 2.0
Security: Requires an admin user
Usage: POST /api/v3/dr-configs
Consumes: application/json

 

{
    "source" : "<Source artifactory instance>",
    "target" : "<Target artifactory instance>"
}	

Produces: application/json 

{
    "active": "NONE",
    "dr_replications_enabled": <true | false>,
    "state": "NONE"
}

 

Example:

$ curl  -X POST 'http://localhost:8080/api/v3/dr-configs' -i -u 'admin:password' -H 'Content-Type: application/json; charset=UTF-8' -T createdr.json

 

 

createdr.json
{
    "source" : "Mexico",
	"target" : "China"
}

Example return: 

 

Example return
{
    "active": "NONE",
    "dr_replications_enabled": false,
    "state": "NONE"
}

 


SCRIPTS 

Get Scripts 

Description: Get a list of all scripts 

Since: 2.0
Security: Requires an admin user
Usage: GET /api/v3/scripts
 
Return codes:

200 - Success

Produces: application/json

[
	{ "name" : "<script name>" }
]

 

Example:

$ curl -XGET 'http://localhost:8080/api/v3/scripts' -uadmin:password

 

 

[
    {
        "name": "Create_repository"
    },
    {
        "name": "Delete_repository"
    },
    {
        "name": "ldap"
    },
    {
        "name": "Create_service"
    }
]
 
200 Success

Get Script User Input

Description: Get a list of required script user inputs  

Since: 2.0
Security: Requires an admin user
Usage: GET /api/v3/scripts/{name}/user_inputs
Return codes:

200 - Success

404 - The entity 'Script' with identifier '<Script-name>' was not found
Produces: application/json
Example:
$ curl -XGET 'http://localhost:8080/api/v3/scripts/{name}/user_inputs' -uadmin:password 

 

 

example output
{
    "ArtifactoryDsl#0#LocalRepositoryDsl#0#description#0": {
        "name": "Enter the required user input value here",
        "description": "Please provide a description",
        "value": "This is a generic description",
        "type": "STRING",
        "multivalued": false
    }
}

Execute Script

Description: Executes the specified scripts on the specified service 

Since: 2.0
Security: Requires an admin user
Usage: PUT /api/v3/execute_script/{name}
Return codes:

200 - Success

404 - Errors based on the input provided. 
Consumes: application/json (only when user input is required by the script)
When the script requires user input, this is the JSON object describing it as returned by Get Script User Input endpoint. 
Produces: application/json

 

[  
   {  
      "instance":{  
         "name":"<instance name>",
         "url":"<instance URL>",
         "type":"<instance type>"
      },
      "status":"< OK | ERROR >",
      "execution_duration":<Duration in seconds>
   }
]

In case of error, output is:

[  
   {  
      "instance":{  
         "name":"<instance name>",
         "url":"<instance URL>",
         "type":"<instance type>"
      },
      "status":"ERROR",
			error: {
   				"type": "<Error type>",
   				"message" : "<Error message>",
   				"details" : [ "<Additional details>" ],
			}, 
      "execution_duration":<Duration in seconds>
   }
]

 

Example:

$ curl -uadmin:password -XPUT http://localhost:8080/api/v3/execute_script/{Script_Name} -d '{}' -H 'Content-Type: application/json'

 

 

example output
[  
   {  
      "instance":{  
         "name":"Mexico",
         "url":"http://172.31.61.159:8081/artifactory",
         "type":"ARTIFACTORY"
      },
      "status":"OK",
      "execution_duration":1622,
      "operation":"UPDATE_REPOSITORY"
   }
]

 



LICENSE BUCKETS

Get Bucket Status 

Description: Get the report for a specified bucket.

Since: 2.0
Security: Requires an admin user
Usage: GET /api/v3/buckets/{identifier}/report
Produces: application/json

 

{
    "id": "<bucket ID>",
    "size": <Number of licenses in the bucket>,
    "licenses": {
        "used": <Number of licenses that are in use>,
        "available": <Number of licenses that are in available>,
        "max_used": <The maximum number of licenses ever used concurrently>
    }
}

Return codes:

200 - Success

 Example:

$ curl -XGET 'http://localhost:8080/api/v3/buckets/415921223/report' -i -u 'admin:password'

 

 

example output
{
    "id": "2435",
    "size": 5,
    "licenses": {
        "used": 0,
        "available": 5,
        "max_used": 0
    }
}

200 Success

 

Attach License 

Description: Attaches a license from the specified bucket to the specified Artifactory service. 

Since: 2.0
Security: Requires an admin user
Usage: POST /api/v3/attach_lic/buckets/{name}
Consumes: application/json

 

{
    "node_id" : "<nodeId of the cluster node to receive the license>",
    "service_name" : "Artifactory service name",
    "deploy" : <true | false>
} 

Produces: application/json

{
    "license_key" : "<license-key>"
} 

 

Return codes:

200 - Success

 Example:

$ curl -POST 'http://localhost:8080/api/v3/attach_lic/buckets/{name}' -i -u 'admin:password' -H 'Content-Type: application/json; charset=UTF-8' -T attachlicense.json

 

 

attachlicense.json
{
    "node_id" : "nodeId",
    "service_name" : "ServiceName",
    "deploy" : false
} 

 

 

example output
{
    "license_key" : "<cHJvZHV...jdHM6CiAgY>"
} 

Attach License Artifactory 5.x HA 

Description: Attaches a number of licenses from the specified bucket to an Artifactory 5.x HA cluster. 

Since: 2.0
Security: Requires an admin user
Usage: POST /api/v3/attach_lic/buckets/{name}
Consumes: application/json

 

{
    "number_of_licenses" : 5,
    "service_name" : "<Service name>",
    "deploy" : < false | true >
} 	

 

Return codes:

200 - Success

409 - "Deployment of multiple license is supported for cluster only"

 Example:

$ curl 'http://localhost:8080/api/v3/attach_lic/buckets/{name}' -i -u 'admin:password' -X POST -H 'Content-Type: application/json; charset=UTF-8' -T attachlicense.json

 

 

attachlicense.json
{
    "number_of_licenses" : 5,
    "service_name" : "ServiceName",
    "deploy" : false
}

AUTHENTICATION

Change Password

Description: Changes a user's password.
Since: 2.1

Security: Users can change their own password. Requires an admin user to change all user passwords.
Usage: PUT /api/v3/auth/changePassword 

Return codes:

204 - No Content
Consumes: application/json

 
PUT /api/v3/auth/changePassword HTTP/1.1
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
Host: localhost:8080
Content-Length: 56

{
"username" : "username",
"password" : "pa$1word"
} 

Version Mappings

To facilitate updating your scripts to use the latest API, the following table presents a mapping between endpoints in V1 and the corresponding endpoints in V2 of the REST API.

CategoryDescriptionMethodV1 EndpointV2 EndpointV3 Endpoint
Services    Get list of  Artifactory servicesGET/api/v1/instances /api/v2/instancesN/A
Add servicePOST/api/v1/instances/api/v2/instances /api/v3/services
Update servicePUTNot available/api/v2/instances/{name} /api/v3/services/{name}
Get repositories for serviceGET/api/v1/instances/{name}/repositories/api/v2/instances/{name}/repositories /api/v3/services/artifactory/{name}/repositories
Delete service by nameDELETE/api/v1/instances/{name}/api/v2/instances/{name} /api/v3/services/{name}
Get all servicesGET  /api/v3/services/
AuthenticationUpdate passwordPUTN/AN/A/api/v3/auth/changePassword
SecurityCreate userPOSTapi/v1/users/api/v2/security/users N/A
Update userPUT/api/v1/users/{name}/api/v2/security/users/{name} N/A
Create user groupPOST/api/v1/userGroups/api/v2/security/user_groups N/A
Update user groupPUT/api/v1/userGroups/{name}/api/v2/security/user_groups/{name} N/A
Create permission targetPOST/api/v1/permissionTargets/api/v2/security/permission_targets N/A
Update permission target by namePUT/api/v1/permissionTargets/{name}/api/v2/security/permission_targets/{name} N/A
License BucketsGet bucket statusGET/api/v1/buckets/{id}/status/api/v2/buckets/{id}/report /api/v3/buckets/{identifier}/report
Attach a licensePOST/api/v1/buckets/{id}/licenses/api/v2/attach_lic/buckets/{id} /api/v3/attach_lic/buckets/{name}
Detach a licenseDELETE/api/v1/buckets/{id}/licenses/api/v2/detach_lic/buckets/{id} /api/v3/attach_lic/buckets/{name}
Attach a license to Artifactory v5.5 and abovePOST  /api/v3/attach_lic/buckets/{name}
Execute Scripts

Create repositoryPOST/api/v1/repositories/api/v2/execute_scripts/repositories N/A
Update repositoryPUT/api/v1/repositories/api/v2/execute_scripts/repositories N/A
Execute scripts on servicePUT/api/v1/instances/api/v2/execute_scripts/instances /api/v3/execute_script/{name}
ScriptsGet scriptsGET/api/v1/scripts/api/v2/scripts /api/v3/scripts
Get script user inputsGET/api/v1/userInputs/api/v2/scripts/user_inputs /api/v3/scripts/{name}/user_inputs
SystemSystem health check (ping) GET/api/v1/ping/api/v2/ping /api/v3/ping
Sites




Create SitePOSTN/AN/A/api/v3/sites
Update SitePOSTN/AN/A/api/v3/sites/{name}
Partial update site by NamePUTN/AN/A/api/v3/services/{name}
Get SiteGETN/AN/A/api/v3/sites/{name}
Get Site ListGETN/AN/A/api/v3/sites/
Delete SiteDELETEN/AN/A/api/v3/sites/{name}
MonitoringGet Serivce StatusGETN/AN/A/services/{name}/monitoring/status
 Get All services statusGETN/AN/A/api/v3/services/monitoring/status
Disaster RecoveryCreate DR Artifactory services pairPOSTN/AN/A/api/v3/dr-configs