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

Mission Control's REST API supports authentication types:

TypeDescription
BasicIf no Authentication provider is set, use your username and password. Or using local admin to execute REST APIs.
Access Token

If Authentication provider is set, users have to use access token as a bearer token in the authorization header.

Example of authentication using the Bearer token:

    1. Create the Access Token.
    2. Run curl -H 'Authorization: Bearer [token] http://localhost:8080/api/v3/services


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. No authentication required. 
Since: 2.0
Usage: GET /api/v3/ping
Example:

GET /api/v3/ping
 
true

PROXIES

Create Proxy

Description: Adds a proxy.

Since: 3.2
Security: Requires an admin user
Usage: POST /api/v3/proxies

Consumes: application/json


Example:

POST /api/v3/proxies HTTP/1.1

{
  "name" : "proxy-01",
  "url" : "http://proxyurl:8080",
  "sites" : [ {
    "source_site" : "source-Site",
    "destination_site" : "destination-Site"
  } ],
  "username" : "username",
  "password" : "password"
}


Example:


$ curl 'http://localhost:8080/api/v3/proxies' -i -u 'admin:password' -X POST -H
'Content-Type: application/json; charset=UTF-8' -d '{
  "name" : "proxy-01",
  "url" : "http://proxyurl:8080",
  "sites" : [ {
      "source_site" : "source-Site",
      "destination_site" : "destination-Site"
      } ],
      "username" : "username",
      "password" : "password"
}'



Create External Proxy

Description: Adds an external proxy.
Since: 3.2
Security: Requires an admin user
Usage: POST /api/v3/proxies
Consumes: application/json


Example:

POST /api/v3/proxies HTTP/1.1

{
   "name" : "proxy-01",
   "url" : "http://proxyurl:8080",
   "sites" : [ {
      "source_site" : "source-Site"
    } ],
    "username" : "username",
    "password" : "password"
}

 


Update Proxy by Name

Description: Updates a proxy.
Since: 3.2
Security: Requires an admin user
Usage: POST /api/v3/proxies/{name}
Consumes: application/json

Example:


PUT /api/v3/proxies/proxy-01 HTTP/1.1

{
  "name" : "proxy-01-1",
  "url" : "http://a53dacff-7d2a-4991-bea0-231abe891e52:8080",
  "sites" : [ {
      "source_site" : "source-Site2",
      "destination_site" : "destination-Site2"
   } ],
   "username" : "username1",
   "password" : "password1"
}

 


Get List of Proxies

Description: Get the list of proxies.
Since: 3.2
Security: Requires an admin user
Usage: Get /api/v3/proxies
Consumes: application/json

Example:


GET /api/v3/proxies HTTP/1.1


[ {
   "name" : "proxy-01",
   "url" : "http://ff121cae-f1f1-4639-85ff-cb07c744c730",
   "sites" : [ {
       "source_site" : "source-site-name",
       "destination_site" : "destination-site-name"
    } ]
}, {
    "name" : "proxy-02",
    "url" : "http://14dc60cb-e3c2-476f-b4a6-263adf70a34d",
    "sites" : [ {
       "source_site" : "source-site-name"
    } ]
} ]


Command line:


$ curl 'http://localhost:8080/api/v3/proxies' -i -u 'admin:password' -H 'Content-Type: application/json; charset=UTF-8'



Get List of Proxies Filtered by Source Service

Description: Get the list of proxies by source service.
Since: 3.2
Security: Requires an admin user
Usage: GET  /api/v3/proxies?src_service={service_name}
Consumes: application/json


Example:


GET /api/v3/proxies?src_service=artifactory HTTP/1.1

[ {
  "name" : "proxy-01",
  "url" : "http://cfc3cf06-18b2-414c-a3e7-12dfd593201d",
  "sites" : [ {
    "source_site" : "source-site-name",
    "destination_site" : "destination-site-name"
  } ]
} ]



Get List of Proxies Filtered by Destination Service


Description: Get the list of proxies filtered by destination service.
Since: 3.2
Security: Requires an admin user
Usage: GET /api/v3/proxies?dest_service={destination_service_name}
Consumes: application/json

Example:


GET /api/v3/proxies?dest_service=artifactory HTTP/1.1

[ {
   "name" : "proxy-01",

   "url" : "http://609c68a0-9e8c-4104-adac-0623914c85bf",
   "sites" : [ {
     "source_site" : "source-site-name",
     "destination_site" : "destination-site-name"
   } ]
} ]



Get List of Proxies Filtered by Source and Destination Service

Description: Get the list of proxies by source service.
Since: 3.2
Security: Requires an admin user
Usage: GET  /api/v3/proxies?src_service={source_service_name}&dest_service={destination_service_name}
Consumes: application/json

Example:


GET /api/v3/proxies?src_service=source-artifactory&dest_service=destination

[ {
   "name" : "proxy-01",
   "url" : "http://609c68a0-9e8c-4104-adac-0623914c85bf",
   "sites" : [ {
     "source_site" : "source-site-name",
     "destination_site" : "destination-site-name"
   } ]
} ]



Get Proxy by Name


Description: Get a proxy by name.
Since: 3.2
Security: Requires an admin user
Usage: GET /api/v3/proxies/{name}
Consumes: application/json


Example:

GET /api/v3/proxies/proxy-01 HTTP/1.1 

{
  "name" : "proxy-01",
  "url" : "http://0277a02d-5267-46c9-a5c9-7836f0bff8fb",
  "sites" : [ {
     "source_site" : "source-Site",
     "destination_site" : "destination-Site"
   } ]
}




Delete Proxy by Name

Description: Removes a proxy from Mission Control.
Since: 3.2
Security: Requires an admin user
Usage: DELETE  /api/v3/proxies/{name}
Consumes: application/json

Example:


DELETE /api/v3/proxies/proxy-01 HTTP/1.1


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. Updated in 3.2 with additional attributes
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>"
	"site_name" : "<Site name">,
	"auth_token": "<Service's authentication token, instead of using the username/password>",
	"pair_with_auth_provider" : "<true | false>",
	"auth_provider" : "<true | false>" 
} 


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",
        "service_type": "jfrt",
        "service_id": "jfrt@01ccgfzxdyqd3y0d816fns0zhh",
        "site": {
           "city": {
               "country_code": "AR",
               "latitude": -34.61315,
               "longitude": -58.37723,
               "name": "Buenos Aires"
           },
           "description": "",
           "name": "Argentina"
        }

    },
    {
        "name": "China",
        "description" : "Artifactory serving development in China",
        "url": "http://10.0.0.8:8081/artifactory",
        "type": "ARTIFACTORY",
        "service_type": "jfrt",
        "service_id": "jfrt@01cdmdjarccxy009wnzmwf06jp",
        "site": {
           "city": {
               "country_code": "CN",
               "latitude": 31.22222,
               "longitude": 121.45806,
               "name": "Shanghai"
           },
           "description": "",
           "name": "China"
        }


    }
]
  
200 Success

Get List of Services with Proxy Based on Source 


Description: Gets the list of services managed by Mission Control with proxy
Since: 3.2
Security: Requires an admin user
Usage: GET request to /api/v3/services?source=Source
Consumes: application/json

Example:


GET /api/v3/services?source=Source%20Artifactory%20Name HTTP/1.1 

[ {
  "name" : "Source Artifactory Name",
  "url" : "http://Source Artifactory Name.com/artifactory",
  "type" : "ARTIFACTORY",
  "service_type" : "jfrt",
  "service_id" : "jfrt@01crqghgxara0b0ej8nct10dyd",
  "site" : {
    "name" : "Source Site Name",
    "description" : "59551ac7-d8a3-426d-90a7-730219f11ddc",
    "city" : {
      "name" : "73955951-ef5c-4864-a118-561b117fdb7c",
      "latitude" : 66.778899,
      "longitude" : 44.556644
    }
  }
}, {
  "name" : "Destination Artifactory Name",
  "url" : "http://Destination Artifactory Name.com/artifactory",
  "type" : "ARTIFACTORY",
  "service_type" : "jfrt",
  "service_id" : "jfrt@01crqghgxf30e91k6gascc1r7p",
  "site" : {
  "name" : "Destination Site Name",
  "description" : "06dce948-ef85-45d6-b600-c2dc8ca57a63",
  "city" : {
  "name" : "c64f2329-2021-49ec-9188-cea1840f9df6",
  "latitude" : 66.778899,
  "longitude" : 44.556644
  }
  },
  "proxy" : {
    "url" : "http://proxy.com" 
  }
} ]

 


Get Service by Name with Proxy based on Source


Description: Get service by name managed by Mission Controlwithproxy.
Since: 3.2
Security: Requires an admin user
Usage: GET /api/v3/services/{name}

Example:


GET /api/v3/services/jfrt%4001crqgh6fyxtpn1eyddfwa1hk1?source=Source%20Artifactory%20Name

{
  "name" : "Destination Artifactory Name",
  "url" : "http://Destination Artifactory Name.com/artifactory",
  "type" : "ARTIFACTORY",
  "service_type" : "jfrt",
  "service_id" : "jfrt@01crqgh6fyxtpn1eyddfwa1hk1",
  "site" : {
  "name" : "Destination Site Name",
  "description" : "31c51fe9-dfa0-48d4-8ce7-675e2b6b1b43",
  "city" : {
    "name" : "28759984-cf1a-41bc-952c-33e4e3a7c4a0",
    "latitude" : 66.778899,
    "longitude" : 44.556644
   }
 },
 "proxy" : {
   "url" : "http://proxy.com"
 }
}



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



ACCESS FEDERATION

Get Access Federation Configuration for a Single Service

Description: Gets the Access Federation configuration for a specific service. Returns the Federation targets configured for the provided service.

Since: 3.3
Security: Requires an admin user
Usage: GET /api/v3/services/access/{serviceName}/federation
Return codes:

200 - Success
400 - The service is not a valid Access Federation candidate.
404 - The service was not found or it is not an Artifactory.
Consumes: application/json


Request Example:

GET /api/v3/services/access/artifactory1/federation HTTP/1.1

 Response Example:

{ "entities" : [ "GROUPS", "USERS" ], "targets" : [ { "name" : "artifactory2", "code" : "access2ServiceId", "url" : "http://localhost:37837" } ] }



Get Access Federation Configuration for All Services 

Description: Gets the Access Federation configurations for all the services.

Since: 3.3
Security: Requires an admin user
Usage: GET /api/v3/services/access/federation?includeNonConfiguredServices=false
Return codes:

200 - Success

Produces: application/json


Request Example:

GET /api/v3/services/access/federation?include_non_configured=false HTTP/1.1

Response Example:

[ { "source" : "artifactory1", "entities" : [ "GROUPS", "USERS" ], "targets" : [ { "name" : "artifactory2", "code" : "access2ServiceId", "url" : "url2" } ] } ]



Configure Access Federation on a Service

Description: Configures Access Federation for a specific Artifactory service. As a pre-requisite, the source and targets must have been configured properly for Access Federation based on this
Since: 3.3
Security: Requires an admin user
Usage: PUT /api/v3/services/access/{serviceName}/federation

Return codes:
200 - Success
400, 422 - Invalid input
404 - Service not found or not an Artifactory


Example Request:

PUT /api/v3/services/access/artifactory1/federation HTTP/1.1 { "entities" : [ "USERS", "GROUPS" ], "targets" : [ { "name" : "artifactory2", "url" : "http://localhost:8080" } ] }

Example Response:

[ { "label" : "Get configuration of artifactory1", "status" : "OK" }, { "label" : "Get Access token from artifactory1", "status" : "OK" }, { "label" : "Check if artifactory2 trusts artifactory1", "status" : "OK" }, { "label" : "Send configuration to artifactory1", "status" : "OK" }, { "label" : "Add target artifactory2 to artifactory1", "status" : "OK" } ]

Get Access Federation Candidates

Description: Gets the Access Federation for a specific service.
Since: 3.3
Security: Requires an admin user
Usage: GET /api/v3/services/access/federation/candidates

Return codes:
200 - Success
 

Request Example:

GET /api/v3/services/access/federation/candidates HTTP/1.1

Response Example:

["service name 1", "service name 2"]



Create Mesh

Description: Creates a mesh topology. As a pre-requisite, the source and targets must have been configured properly for Access Federation based on this

Since: 3.3
Security: Requires an admin user
Usage: POST /api/v3/services/access/federation/create_mesh
Return codes:

200 - Success
400, 422 - Invalid input
404 - Service not found or not an Artifactory
  

Request Example:

POST /api/v3/services/access/federation/create_mesh HTTP/1.1

Response Example:

{ "services": [ "service name 1", "service name 2" ], "entities": [ "USERS", "GROUPS", "PERMISSIONS", "TOKENS" ] }

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

SUPPORT


Create a Support Bundle

Description: Create a new support bundle.
Since: 3.2
Security: Requires an admin user
Notes: All bundle items are optional.
Usage: POST /api/v3/system/support/bundle

Return codes:
202 - Support bundle is being created and will be available soon
400 - Invalid option values
403 - Unauthorized

Sample Usage:

POST /api/v3/system/support/bundle HTTP/1.1
 
{
  "name" : "My support bundle",
  "description" : "Support bundle generated because of issue XYZ",
  "parameters" : {
    "configuration" : true,
    "system" : true,
    "logs" : {
       "include" : true,
       "start_date" : "2018-09-19",
       "end_date" : "2018-09-20"
   },
   "thread_dump" : {
     "count" : 1,
     "interval" : 0
   }
  }
}


Example:


$ curl -X POST -uadmin:password https://my-mission-control.jfrogdev.co/api/v3/system/support/bundle -H 'Content-Type: application/json' \
  -d '{
  "name": "JFMC support bundle",
  "description": "Support bundle generated because of issue with XYZ",
  "parameters": {
    "configuration": true,
    "system": true,
    "thread_dump": {
      "count": 1,
      "interval": 0
    },
    "logs": {
      "include": true,
      "start_date": "2018-12-25",
      "end_date": "2019-01-07"
    }
  }
}'



Get List of Support Bundles 

Description: Get the list of available support bundles.
Since: 3.2
Security: Requires an admin user
Usage: GET /api/v3/system/support/bundles

Return codes:
200 - Successful
403 - Unauthorized

Example:


GET /api/v3/system/support/bundles HTTP/1.1

Response:

{
  "count" : 2,
  "bundles" : [ {
    "name" : "A",
    "description" : "aaa",
    "id" : "1",
    "created" : "2018-10-01T09:50:11Z"
}, {
   "name" : "B",
   "id" : "2",
   "created" : "2018-10-01T09:50:11Z"
  } ]
}



Get Details of a Support Bundle 

Description: Gets the details of a specific support bundle.
Since: 3.2
Security: Requires an admin user
Usage: GET  /api/v3/system/support/bundle/{id}

Return codes:
200 - Successful
403 - Unauthorized
404 - Supplied ID does not refer to an existing support bundle

Example:

GET /api/v3/system/support/bundle/SUPP20180912154413548991 HTTP/1.1

Response:


 
{
  "name" : "issue #1234",
  "description" : "Support bundle created for issue #1234 investigation",
  "artifactory" : {
     "service_id" : "jfrt@12d0hodgwb0bz427ldnyyk22se",
     "bundle_url" : "http://artifactory.jfrog.com/artifactory/jfrog-admin-supportbundle/SUPP20180912154413548991/jfmc/01c7b8rg70nrqr1cck7k4x0yp7"
   },
   "parameters" : {
     "configuration" : true,
     "system" : true,
     "logs" : {
        "include" : true,
        "start_date" : "2018-09-30",
        "end_date" : "2018-10-01"
   },
     "thread_dump" : {
       "count" : 1,
       "interval" : 0
   }
 
  },
  "available" : 5,
  "created" : "2018-10-01T09:50:10Z"
}



Download a Support Bundle 

Description: Downloads a support bundle as a ZIP file.
Since: 3.2
Security: Requires an admin user. You need to have the "Download folder" permission enabled on Artifactory.
Usage: GET  /api/v3/system/support/bundle/{id}/archive

Return codes:
200 - Successful
403 - Unauthorized (it may be that the "Download folder" option is not enabled on the Authentication Provider Artifactory)
404 - Supplied ID does not refer to an existing support bundle or the ZIP cannot be found in the Authentication Provider Artifactory repository

Example:

GET /api/v3/system/support/bundle/SUPP20180912154413548991/archive HTTP/1.1



Delete a Support Bundle 

Description: Deletes a support bundle, along with the ZIP file in Artifactory.
Since: 3.2
Security: Requires an admin user
Usage: DELETE  /api/v3/system/support/bundle/{id}

Return codes:
204 - Successful
403 - Unauthorized
404 - Supplied ID does not refer to an existing support bundle

Example:


DELETE /api/v3/system/support/bundle/SUPP20180912154413548991 HTTP/1.1



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 Buckets

Description: Retrieves all the license buckets in the system.

Since: 3.1.1
Security: Requires an admin user
Usage: GET /api/v3/buckets

Return codes:

200 - Success

Produces: application/json
[
	{
		"id" : "<bucket id>",
  		"name" : "<bucket name>",
  		"size" : <number of licenses in bucket>,
  		"license_type": "<ENTERPRISE | EDGE>"
	}
]

Sample Usage:

GET /api/v3/buckets
 
[
{
  "id" : "12345",
  "name" : "bucket-test-1",
  "size" : 10,
  "license_type": "ENTERPRISE" 
},
{
  "id" : "1234567",
  "name": "bucket-test-2",
  "size" : 5,
  "license_type": "EDGE" 
}
]


Create Bucket 

Description: Creates a new License Bucket.

Since: 3.0.0
Security: Requires an admin user
Usage: POST /api/v3/buckets

Return codes:

201 - Created
409 - Name '<Bucket name>' already exists
409 - Url '<Bucket URL>' already exists

Consumes: application/json


{          
    "bucket_name" : "<Bucket name>",
    "bucket_url" : "<Bucket URL>",
    "bucket_key" : "<Bucket key>"
}

Example:


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

createbucket.json


{
    "bucket_name" : "main-bucket",
    "bucket_url" : "https://bintray.jfrog.com/license-buckets/test_jfrog.com/12345678/12345678.json?expiry=1528199600307&id=ABCDEFGhiJkLmNoPQR",
    "bucket_key" : "16629dbf7fefc9d179b36ba005685c2dd8376aad3278178e735da1633c6bd3c6"
}
201 Created
 
{
  "subject" : "JFrog",
  "product_name" : "Artifactory",
  "product_id" : 6,
  "license_type" : "HA",
  "issued_date" : "2018-04-12T16:02:55.549+03:00",
  "valid_date" : "2019-04-12T16:02:54.759+03:00",
  "quantity" : 10,
  "signature" : "06307c34405e6ab70c5d249a7ba7cffd81947d5f",
  "name" : "main-bucket",
  "used" : 0,
  "url" : "https://bintray.jfrog.com/license-buckets/test_jfrog.com/12345678/12345678.json?expiry=1528199600307&id=ABCDEFGhiJkLmNoPQR"
}

Delete Bucket

Description: Deletes a bucket.
Since: 3.0.0 Security: Requires an admin user
Usage: DELETE /api/v3/buckets/{name}
Return codes: 204 - Success
Example:


$ curl -XDELETE 'http://localhost:8080/api/v3/buckets/main-bucket' -uadmin:password  -H "Content-Type: application/json"
 
204 No Content

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

Example:

{
    "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": "415921223",
    "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
}

SETTINGS


Update Base URL 

Description: Sets the base URL that will be used by other services to communicate with Mission Control 
Since: 3.2
Security: Requires an user with admin privileges
Usage: PUT /api/v3/settings/base_url
Request Parameters: 
base_url - Externally accessible URL
Sample Usage:

curl 'http://localhost:8080/api/v3/settings/base_url' -i -u 'admin:password' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{
  "base_url" : "http://baseUrl-to-mc:8080/"
}'
204 No Content

AUTHENTICATION


Create Token 

Description: Creates an access token 
Since: 3.0
Security: Requires a valid user
Usage: POST /api/v3/security/token
Request Parameters: 
username - the user to which the token is assigned
expires_in - token validity period in seconds
refreshable - if true, the token can be refreshed
Content-Type: application/x-www-form-urlencoded
Produces: application/json  
Sample Usage:

curl 'http://localhost:8080/api/v3/security/token' -i -u 'admin:password' -X POST -H
{
    "username" : "central-user",
    "expires_in" : 1000,
    "refreshable" : true
}
 
Response:
{
    "access_token": "eyJ2Z...kMzA",
    "expires_in": 1000,
    "refresh_token": "2b5f...0664",
    "scope": "applied-permissions/user",
    "token_type": "Bearer"
}


Change Password 

Description: Changes 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
Request Parameters: 
username - the user for which the password is being changed
password - new password
Consumes: application/json
Return codes: 204 - No Content  
Sample Usage:

$ curl 'http://localhost:8080/api/v3/auth/changePassword' -i -u 'admin:password' -X PUT -d username=admin -d password=pa$1word

204 No Content

Revoke Token 

Description: Revokes the access token

Since: 3.0
Security: Requires a valid user
Usage: POST /api/v3/security/token/revoke
Content-Type: application/x-www-form-urlencoded
Return code:
204 - No Content 

Sample Usage:


curl 'http://localhost:8080/api/v3/security/token/revoke' -i -u 'admin:password' -X DELETE -H 'Content-Type: application/json'



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 and V3 of the REST API.

CategoryDescriptionMethodV1 Endpoint (Not Supported in V 3.0)V2 Endpoint (Not Supported in V 3.0)V3 Endpoint
ProxiesCreates a proxyPOSTN/AN/A /api/v3/proxies
Adds an external proxyPOSTN/AN/A /api/v3/proxies
Updates a proxy by namePOSTN/AN/A /api/v3/proxies/{name}
Gets a list of proxiesGETN/AN/A /api/v3/proxies
Gets the list of proxies by source serviceGETN/AN/A /api/v3/proxies?src_service={service_name}

Gets list of Proxies Filtered by Destination Service

GETN/AN/A /api/v3/proxies?dest_service={destination_service_name}

Gest a list of Proxies Filtered by Source and Destination Service

GETN/AN/A/api/v3/proxies?src_service={source_service_name}&dest_service={destination_service_name}
Gets a proxy by nameGETN/AN/A/api/v3/proxies/{name}
Removes a proxy from Mission ControlDELETEN/AN/A /api/v3/proxies/{name}
 Get a List of Services with Proxy Based on SourceGETN/AN/A /api/v3/services?source=Source
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/
Get service by name managed with proxy based on sourceGETN/AN/A/api/v3/services/{name}

Get List of Services with Proxy Based on Source

GETN/AN/A/api/v3/services?source=Sourc
AuthenticationCreates an access tokensPUTN/AN/A/api/v3/security/token

Update 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 BucketsCreates a new license bucketGETN/AN/A/api/v3/buckets
Deletes a bucketDELETEN/AN/A/api/v3/buckets/{name}
Get 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
SupportCreate a support bundlePOSTN/AN/A/api/v3/support/bundle

Get list of support bundles 

GETN/AN/A/api/v3/support/bundles

Get details of a support bundle 

GETN/AN/A/api/v3/support/bundle/{id}
Download a support bundleGETN/AN/A/api/v3/support/bundle/{id}/archive
Delete a support bundleDELETEN/AN/A /api/v3/support/bundle/{id}
Disaster RecoveryCreate DR Artifactory services pairPOSTN/AN/A/api/v3/dr-configs