Distribution 1.x

Using the latest JFrog products?
JFrog Platform User Guide

Expand all   Collapse all

JFrog Distribution 1.x Documentation
To get the latest version, go to the JFrog Unified Platform

Skip to end of metadata
Go to start of metadata

Overview

Distribution 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

Distribution 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.

GENERAL

Test connection

Description: Test connection with distribution.

Since: 1.0
Security: No authentication required.
Usage: GET /api/v1/system/ping
Request headers: N/A
Consumes: N/A


Request Example
$ curl -XGET "http://localhost:8080/api/v1/system/ping"

Response status codes:

200 - Connection healthy
500 - Error. One or more of the databases is unavailable

Response headers: N/A
Produces: application/json


Response
On Success
{
  "status_code”: 200,
  "message": "ok"
}
 
On Error
{
  "status_code”: 500,
  "message": "The following services are unavailable: database, redis, distributor"
}

Get system info

Description: Get general information, including error details if system is unstable. NOTE: Do not set a passphrase for the signing keys. When creating release bundles through the UI, JFrog Distribution does not currently support entering a passphrase.

Since: 1.0
Security: No authentication required.
Usage: GET /api/v1/system/info
Request headers: N/A
Consumes: N/A


Request Example
$ curl -XGET "http://localhost:8080/api/v1/system/info"


Response status codes:

200 - Success

Response headers: N/A
Produces: application/json


Response
{
  "status": "STABLE",
  "message": "...",
  "version": "1.0",
  "service_id": "jfds@..."
}

Page Contents

 

Get System Settings

Description: get system settings
Since: 1.6
Security: Admin only
Usage: GET /api/v1/system/settings
Request headers: N/A
Consumes: N/A

Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/system/settings"

Response status codes:
200 - Success

Response headers: N/A

Produces: application/json

Response
{
      call_home_enabled: true
}

Update System Settings

Description: update system settings
Since: 1.6
Security: Admin only
Usage: POST /api/v1/system/settings
Request headers: N/A
Consumes: application/json

system_settings.json
{
      call_home_enabled: true
}
FieldTypeRequiredDefault ValueSinceDescription
call_home_enabled

Boolean

no

false

1.6

If enabled, sending usage statistics to JFrog

Request Example
$ curl -XPOST -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/system/settings" -T system_settings.json

Response status codes:

200 - Success

SIGNING KEYS

Set signing key for Distribution

Description: Set GPG signing key for distribution. This key will be used to sign release bundles.

Since: 1.0
Security: Admin only.
Usage: PUT /api/v1/keys/pgp
Request headers: N/A
Consumes: application/json


gpg.json
{
  "public_key":  "-----BEGIN GPG PUBLIC KEY BLOCK-----
                  ....
                  -----END GPG PUBLIC KEY BLOCK-----",
  "private_key": "-----BEGIN GPG PRIVATE KEY BLOCK-----
                  ....
                  -----END GPG PRIVATE KEY BLOCK-----"
}
Request Example
$ curl -XPUT -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/keys/pgp" -T gpg.json


Response status codes:

200 - Keys were successfully set.

Response headers: N/A
Produces: application/json


Response
{
  "status_code”: 201,
  "message": "Set PGP public & private key"
}


RELEASE BUNDLES

Create Release Bundle Version

Description: Create a new release bundle version.

Since: 1.0
Note: A release bundle version can include up to 100k binaries.

Exceeding the Supported Number of Binaries

The 100k max limit is not fixed and can be exceeded however please note it has not been tested and is at your own risk.


Security: Authenticated users only. User must have matching Release Bundle write permissions.
Usage: POST api/v1/release_bundle
Request headers: 
X-GPG-PASSPHRASE - String - the passphrase for the signing key, if applicable
Consumes: application/json


createbundle.json
{
  "name": "",
  "version": "",
  "dry_run": true|false,
  "sign_immediately": true|false,
  "storing_repository": "repository-name"|null,
  "store_at_source_artifactory": true|false,
  "description": "",
  "release_notes": {
    "syntax": "markdown|asciidoc|plain_text",
    "content": ""
  }, 
  "spec": {
    "source_artifactory_id": "jfrt@...",
    "queries": [
      {
        "aql": "items.find({ \"repo\" : \"example-repo-local\" })",
        "query_name": "",
        "mappings": [
          {
            "input": "regex",
            "output": "$1/$2"
          }
        ],
        "added_props": [
          {
            "key": "",
            "values": [""]
		  }
        ]
      }
    ]
  }
}
FieldTypeRequiredDefault ValueSinceDescription
name

String

yes

N/A

1.0

Release bundle name

version

String

yes

N/A

1.0

Release bundle version

dry_run

Boolean

no

true

1.0

If true, only parses and validates.

sign_immediately

Boolean

no

false

1.2

If true, automatically signs the release bundle version.

storing_repository

String

no

null

1.3

A repository name at source Artifactory to store release bundle artifacts in. If not provided, Artifactory will use the default one (requires Artifactory 6.5 or later).

store_at_source_artifactory

Boolean

no

true

1.3

The flag indicates, whether to store release bundle version in the source Artifactory while signing (requires Artifactory 6.5 or later)

description

String

no

null

1.0

Description of the release bundle

release_notes

String

no

null

1.0

Describes the release notes for the release bundle version

release_notes.syntax

String

no

"plain_text"

1.0

The syntax for the release notes

release_notes.content

String

yes

N/A

1.0

The content of the release notes

spec

Object

yes

N/A

1.0

Describes the specification by artifacts are gathered and distributed in this release bundle

spec.source_artifactory_id

String

yes

N/A

1.0

A single Artifactory service id from which artifacts will be gathered.

spec.queries

List (Object)

yes

N/A

1.0

List of query objects to gather artifacts by.

spec.queries.aql

String

yes

N/A

1.0

AQL query to gather the artifacts from Artifactory

spec.queries.query_name

String

no

"query-{index}"

1.0

A name to be used when displaying the query object

spec.queries.added_props

List (Object)

no

null

1.0

List of added properties which will be added to the artifacts after distribution of the release bundle

spec.queries.added_props.key

String

yes

N/A

1.0

Property key to be created or updated after distribution of the release bundle

spec.queries.added_props.values

List (String)

no

[ ]

1.0

List of values to be added to the property key after distribution of the release bundle

spec.queries.mappings

List (Object)

no

null

1.0

List of mappings, which are applied to the artifact paths after distribution of the release bundle

spec.queries.mappings.input

String

yes

N/A

1.0

Regex matcher for artifact paths

spec.queries.mappings.output

String

yes

N/A

1.0

Replacement for artifact paths matched by the "input" matcher. Capture groups can be used as "$1".

  

Request Example
$ curl -XPOST -u admin:password -H "Content-Type: application/json" -H "X-GPG-PASSPHRASE: passphrase" "http://localhost:8080/api/v1/release_bundle" -T createbundle.json

Response status codes:

201 - Successfully created release bundle version
409 - Release bundle with same name and version already exists
X    - Status code for error passed from Artifactory AQL

Response headers: N/A
Produces: application/json

Response
 {
	"name": "bundle-name",
	"version": "1.0",
	"state": "OPEN",
	"created": "2018-03-14T10:19:30.678Z",
	"artifacts": [
		{
            "source_artifactory_id": "jfrt@01c8d4y8q2xj2y1s8s2zv00a28",
			"checksum": "0651d26f4cc6ed60cd9d273c440daf7617459d3f6e3d512188ff19d4933e4ff6",
			"source_repo_path": "conanx/demo/sample-conan1/1.0/testing/export/conanfile.py",
			"target_repo_path": "conanx/demo/sample-conan1/1.0/testing/export/conanfile.py",
			"props": [
				{
					"key": "conan.package.version",
					"values": [
						"1.0"
					]
				},
				...
			]
		},
		{
			"xray_scan_info": {
			"blocked": boolean.
			"blocked_reason": string (null if not blocked)
		},
		...
	],
	"archived": false
}

NPM, Bower and NuGet Package Types

When working with package types such as NPM, Bower and NuGet, that require transitive dependencies, you will need to create two separate release bundles: 1. An artifacts release bundle, and 2. A dependencies release bundle.

You can generate the build.info using JFrog CLI, and create the release bundles using the following dependency and artifact AQL queries:

Artifact AQL
builds.find({"name":"buileName", "number":"buildNumber"}).include("module.artifact.item")
Dependency AQL
builds.find({"name":"buildName", "number":"buildNumber"}).include("module.dependency.item")

Update Release Bundle Version

Description: Updates an existing unsigned release bundle version.

Since: 1.2
Security: Authenticated users only. User must have matching Release Bundle write permissions.
Usage: PUT api/v1/release_bundle/:name/:version
Request headers: 
X-GPG-PASSPHRASE - String - the passphrase for the signing key, if applicable
Consumes: application/json


updatebundle.json
{
  "dry_run": true|false,
  "sign_immediately": true|false,
  "description": "",
  "release_notes": {
    "syntax": "markdown|asciidoc|plain_text",
    "content": ""
  }, 
  "spec": {
    "source_artifactory_id": "jfrt@...",
    "queries": [
      {
        "aql": "items.find({ \"repo\" : \"example-repo-local\" })",
        "query_name": ""
        "mappings": [
          {
            "input": "regex",
            "output": "$1/$2"
          }
        ],
        "added_props": [
          {
            "key": "",
            "values": [""]
        ]
      }
    ]
  }
}
FieldTypeRequiredDefault ValueSinceDescription
dry_run

Boolean

no

true

1.2

If true, only parses and validates

sign_immediately

Boolean

no

false

1.2

if true, automatically signs the release bundle version.

storing_repository

String

no

null

1.3

A repository name at source Artifactory to store release bundle artifacts in. If not provided, Artifactory will use the default one (requires Artifactory 6.5 or later).

store_at_source_artifactory

Boolean

no

true

1.3

The flag indicates, whether to store release bundle version in the source Artifactory while signing (requires Artifactory 6.5 or later).

description

String

no

null

1.2

Description of the release bundle

release_notes

String

no

null

1.2

Describes the release notes for the release bundle version

release_notes.syntax

String

no

"plain_text"

1.2

The syntax for the release notes

release_notes.content

String

yes

N/A

1.2

The content of the release notes

spec

Object

yes

N/A

1.2

Describes the specification by artifacts are gathered and distributed in this release bundle

spec.source_artifactory_id

String

yes

N/A

1.2

A single Artifactory service id from which artifacts will be gathered.

spec.queries

List (Object)

yes

N/A

1.2

List of query objects to gather artifacts by.

spec.queries.aql

String

yes

N/A

1.2

AQL query to gather the artifacts from Artifactory

spec.queries.query_name

String

no

"query-{index}"

1.2

A name to be used when displaying the query object

spec.queries.added_props

List (Object)

no

null

1.2

List of added properties which will be added to the artifacts after distribution of the release bundle

spec.queries.added_props.key

String

yes

N/A

1.2

Property key to be created or updated after distribution of the release bundle

spec.queries.added_props.values

List (String)

no

[ ]

1.2

List of values to be added to the property key after distribution of the release bundle

spec.queries.mappings

List (Object)

no

null

1.2

List of mappings, which are applied to the artifact paths after distribution of the release bundle

spec.queries.mappings.input

String

yes

N/A

1.2

Regex matcher for artifact paths

spec.queries.mappings.output

String

yes

N/A

1.2

Replacement for artifact paths matched by the "input" matcher. Capture groups can be used as "$1".

  

Request Example
$ curl -XPUT -u admin:password -H "Content-Type: application/json" -H "X-GPG-PASSPHRASE: passphrase" "http://localhost:8080/api/v1/release_bundle/:name/:version" -T updatebundle.json

Response status codes:

200 - Successfully updated release bundle version
400 - Release bundle version is signed
X - Status code for error passed from Artifactory AQL

Response headers: N/A
Produces: application/json

Response
 {
	"name": "bundle-name",
	"version": "1.0",
	"state": "OPEN",
	"created": "2018-03-14T10:19:30.678Z",
	"artifacts": [
		{
            "source_artifactory_id": "jfrt@01c8d4y8q2xj2y1s8s2zv00a28",
			"checksum": "0651d26f4cc6ed60cd9d273c440daf7617459d3f6e3d512188ff19d4933e4ff6",
			"source_repo_path": "conanx/demo/sample-conan1/1.0/testing/export/conanfile.py",
			"target_repo_path": "conanx/demo/sample-conan1/1.0/testing/export/conanfile.py",
			"props": [
				{
					"key": "conan.package.version",
					"values": [
						"1.0"
					]
				},
				...
			]
		},
		{
			"xray_scan_info": {
			"blocked": boolean.
			"blocked_reason": string (null if not blocked)
		},
		...
	],
	"archived": false
}

NPM, Bower and NuGet Package Types

When working with package types such as NPM, Bower and NuGet, that require transitive dependencies, you will need to create two separate release bundles: 1. An artifacts release bundle, and 2. A dependencies release bundle.

You can generate the build.info using JFrog CLI, and create the release bundles using the following dependency and artifact AQL queries:

Artifact AQL
builds.find({"name":"buileName", "number":"buildNumber"}).include("module.artifact.item")
Dependency AQL
builds.find({"name":"buildName", "number":"buildNumber"}).include("module.dependency.item")

Sign Release Bundle Version

Description: Signs a release bundle version and stores it in the source Artifactory (requires Artifactory 6.5 or later) in the storing repository.

Since: 1.2
Security: Authenticated users only. User must have matching Release Bundle write permissions.
Usage: POST api/v1/release_bundle/:name/:version/sign
Request headers: 
X-GPG-PASSPHRASE - String - the passphrase for the signing key, if applicable


Request Example
$ curl -XPOST -u admin:password -H "Content-Type: application/json" -H "X-GPG-PASSPHRASE: passphrase" "http://localhost:8080/api/v1/release_bundle/:name/:version/sign"
FieldTypeRequiredDefault ValueSinceDescription
storing_repository

String

no

null

1.3

A repository name at source Artifactory to store release bundle artifacts in. If not provided, Artifactory will use the default one (requires Artifactory 6.5 or later).


Response status codes:

200 - Successfully signed release bundle version
400 - Release bundle version is already signed

Response headers: N/A
Produces: application/json

Response
 {
	"name": "bundle-name",
	"version": "1.0",
	"state": "SIGNED",
	"created": "2018-03-14T10:19:30.678Z",
	"artifacts": [
		{
            "source_artifactory_id": "jfrt@01c8d4y8q2xj2y1s8s2zv00a28",
			"checksum": "0651d26f4cc6ed60cd9d273c440daf7617459d3f6e3d512188ff19d4933e4ff6",
			"source_repo_path": "conanx/demo/sample-conan1/1.0/testing/export/conanfile.py",
			"target_repo_path": "conanx/demo/sample-conan1/1.0/testing/export/conanfile.py",
			"props": [
				{
					"key": "conan.package.version",
					"values": [
						"1.0"
					]
				},
				...
			]
		},
		...
	],
	"archived": false
}


Get all Release Bundles Versions

Description: Returns all the release bundle versions. This endpoint supports pagination, returning up to 10 release bundles per page.

Since: 1.0
Security: Authenticated users only. Only release bundles which the user has read permission for are displayed.
Usage: GET api/v1/release_bundle[?start_pos=:position]
Request headers: N/A
Consumes: N/A


Request Example
$ curl -XGET -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/release_bundle?start_pos=0"


Response status codes:

200 - Success

Response headers: 
X-RangeLimit-StartPos - number
X-RangeLimit-EndPos  - number
X-RangeLimit-Total       - number

Produces: application/json


Response
[
	{
		"name": "release-bundle-name",
		"version": "1.0.0",
		"state": "OPEN",
		"description": "release bundle description text",
        "release_notes": {
            "content": "release notes text",
            "syntax": "plain_text"
        },
		"created": "2018-03-14T17:36:35.416Z",
		"artifacts": [
			{
                "source_artifactory_id": "jfrt@01c8jp98k28pd21556kq9p0dwc",
				"checksum": "0bd5d1e46180436132a86d3d3ec9ddfd7ab0023ac4648f4448fde6e41fffae54",
				"source_repo_path": "maven-1521048945483/org/pom/test/multi1/1.1/multi1-1.1.jar",
				"target_repo_path": "maven-1521048945483/org/pom/test/multi1/1.1/multi1-1.1.jar"
                "props": [
					{
						"key": "build.timestamp",
						"values": [
							"1521049005953"
						]
					},
					...
				]
			},
			{
				"xray_scan_info": {
				"blocked": boolean.
				"blocked_reason": string (null if not blocked)
			},
			...
		],
		"archived": false
	},
    ...
]


Get Release Bundle Versions

Description: Returns all the release bundle versions. This endpoint supports pagination, returning up to 10 release bundles per page.

Since: 1.0
Security: Authenticated users only. User must have read permission for the release bundle.
Usage: GET api/v1/release_bundle/:name[?start_pos=:position]
Request headers: N/A
Consumes: N/A


Request Example
$ curl -XGET -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/release_bundle/bundle1?start_pos=0"


Response status codes:

200 - Success
404 - Release bundle not found
Response headers: 
X-RangeLimit-StartPos - number
X-RangeLimit-EndPos  - number
X-RangeLimit-Total       - number

Produces: application/json


Response
[
  {
    "name": "release-bundle-name",
    "version": "1",
	"state": "OPEN",
    "description": "release bundle description text",
    "release_notes": {
      "content": "release notes description text",
      "syntax": "plain_text"
    },
    "created": "2018-03-14T17:36:35.416Z",
    "artifacts": [
      {
	    "checksum": "5880e05b5886a2fcd9a5a6dace38cd4f243affa06719c5e63116b16094e95a31",
        "props": [
	      {
		    "key": "build.timestamp",
		    "values": ["1521049005953"]
		  },
		  ...
	    ],
	    "source_artifactory_id": "jfrt@01c8d4y8q2xj2y1s8s2zv00a28",
	    "source_repo_path": "artifactory-generic/bintray-client-java-api-0.9.2.jar",
	    "target_repo_path": "artifactory-generic/bintray-client-java-api-0.9.2.jar"
	  },
      ...
    ],
    "archived": false
  },
  ...
] 


Get Release Bundle Version

Description: View a specific release bundle version. Multiple response formats are supported.

Since: 1.0
Security:  Authenticated users only. User must have read permission for the release bundle.
Usage: GET api/v1/release_bundle/:name/:version[?format=json | jws | jose]
Request headers: N/A
Consumes: N/A


Request Example
$ curl -XGET -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/release_bundle/bundle1/1.0.0?format=json"


Response status codes:

200 - Success
404 - Release bundle or release bundle version not found
Response headers: N/A

Produces: application/json (default)


format=json
{
  "name": "bundle-name",
  "version": "1.0.0",
  "state": "OPEN",
  "description": "Bundle description",
  "release_notes": {
    "content": "release notes description text",
    "syntax": "plain_text"
  },
  "created": "2018-05-02T08:45:16.860Z",
  "artifacts": [
    {
      "source_artifactory_id": "jfrt@01cc8hm002py3z1y5yq5t90xrt",
      "source_repo_path": "example-repo-local/Screen Shot 2018-04-05 at 10.47.16.png",
      "target_repo_path": "example-repo-local/achange/Screen Shot 2018-04-05 at 10.47.16.png",
      "checksum": "5a730b01e81e2aa3b5188bcef3be8e4e7d61f83b6156b22a33c9a3f23ff38e19",
      "props": [
        {
          "key": "jira",
          "values": ["1"]
        }
      ]
    },
    ...
  ],
  "archived": false
}
 
Produces: application/jose+json (format=jws) 

format=jws
{
    "header": "eyJraWQiOiIzZWFiNGEiLCJhbGciOiJSUzI1NiJ9",
    "payload": "eyJuYW1lIjoiYnVuZGxlLW5hbWUiLCJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXNjcmlwdGlvbiI6IkJ1bmRsZSBkZXNjcmlwdGlvbiIsInJlbGVhc2Vfbm90ZXMiOnsiY29udGVudCI6InJlbGVhc2Ugbm90ZXMgZGVzY3JpcHRpb24gdGV4dCIsInN5bnRheCI6InBsYWluX3RleHQifSwiY3JlYXRlZCI6IjIwMTgtMDUtMDJUMDg6NDU6MTYuODYwWiIsImFydGlmYWN0cyI6W3sicmVwb19wYXRoIjoiZXhhbXBsZS1yZXBvLWxvY2FsL2FjaGFuZ2UvU2NyZWVuIFNob3QgMjAxOC0wNC0wNSBhdCAxMC40Ny4xNi5wbmciLCJjaGVja3N1bSI6IjVhNzMwYjAxZTgxZTJhYTNiNTE4OGJjZWYzYmU4ZTRlN2Q2MWY4M2I2MTU2YjIyYTMzYzlhM2YyM2ZmMzhlMTkiLCJwcm9wcyI6W3sia2V5IjoiamlyYSIsInZhbHVlcyI6WyIxIl19XX0seyJyZXBvX3BhdGgiOiJleGFtcGxlLXJlcG8tbG9jYWwvYWNoYW5nZS9TY3JlZW4gU2hvdCAyMDE4LTA0LTA1IGF0IDEwLjQ3LjE2ICgyKS5wbmciLCJjaGVja3N1bSI6IjIzMzY2Mzk5N2EyZGYxY2FmZDZhZWI1NjkxNjZhZjkxZjYzZDQwZjRmNDFiNjgxY2JlN2RmMjlkMWE1YzE3MGEiLCJwcm9wcyI6W3sia2V5IjoiamlyYSIsInZhbHVlcyI6WyIxIl19XX0seyJyZXBvX3BhdGgiOiJleGFtcGxlLXJlcG8tbG9jYWwvYWNoYW5nZS9TY3JlZW4gU2hvdCAyMDE4LTA0LTA1IGF0IDEwLjQ3LjE2IDEucG5nIiwiY2hlY2tzdW0iOiI1YTczMGIwMWU4MWUyYWEzYjUxODhiY2VmM2JlOGU0ZTdkNjFmODNiNjE1NmIyMmEzM2M5YTNmMjNmZjM4ZTE5IiwicHJvcHMiOlt7ImtleSI6ImppcmEiLCJ2YWx1ZXMiOlsiMSJdfV19LHsicmVwb19wYXRoIjoiZXhhbXBsZS1yZXBvLWxvY2FsL2FjaGFuZ2UvU2NyZWVuIFNob3QgMjAxOC0wNC0wNSBhdCAxMC40Ny4xNiAoMykucG5nIiwiY2hlY2tzdW0iOiJjYmZjZjk0NzkzYzQ1ZTk5NmY2YTQxODY5M2ZjYjBhZDU1NzRkMzJiYzUwN2NjNmVjMDAzMDkxMmFjMWQ3MDUzIiwicHJvcHMiOlt7ImtleSI6ImppcmEiLCJ2YWx1ZXMiOlsiMSJdfV19XX0",
    "signature": "QWzTD2uXhLw5FW1483qEYA_h47jak8YE24mLwuF1UcT9yTYZBdEMrFWTz0uZVrPtlqi65Ek6oNeSFZO657sjpuTOpfPIg053nxOoIa4mxlxMS5nCM50Xj3qobcll0P_sX8Il8AGWbX9oI9HvSGAKYbxmu-3kVs0W1tCacb_VuHsL5KkgY2Thq5dBKhQ73aS1cE-CnFobQKGcsx10eFhEFV8VbajGLpKV8nhERDE4XA5oRARA-CczLlEYNnvn5aRD-Q1n5yI7Cys8hoDIxDLT2OCQ5alb9h4D4w7mGJrtQG0xNWsstGOTSL1HLXAe27qvBxCIsp6afX675AkOs1Eg0g"
}
 
Produces: application/jose (format=jose) 

format=jose
eyJraWQiOiIzZWFiNGEiLCJhbGciOiJSUzI1NiJ9.eyJuYW1lIjoiYnVuZGxlLW5hbWUiLCJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXNjcmlwdGlvbiI6IkJ1bmRsZSBkZXNjcmlwdGlvbiIsInJlbGVhc2Vfbm90ZXMiOnsiY29udGVudCI6InJlbGVhc2Ugbm90ZXMgZGVzY3JpcHRpb24gdGV4dCIsInN5bnRheCI6InBsYWluX3RleHQifSwiY3JlYXRlZCI6IjIwMTgtMDUtMDJUMDg6NDU6MTYuODYwWiIsImFydGlmYWN0cyI6W3sicmVwb19wYXRoIjoiZXhhbXBsZS1yZXBvLWxvY2FsL2FjaGFuZ2UvU2NyZWVuIFNob3QgMjAxOC0wNC0wNSBhdCAxMC40Ny4xNi5wbmciLCJjaGVja3N1bSI6IjVhNzMwYjAxZTgxZTJhYTNiNTE4OGJjZWYzYmU4ZTRlN2Q2MWY4M2I2MTU2YjIyYTMzYzlhM2YyM2ZmMzhlMTkiLCJwcm9wcyI6W3sia2V5IjoiamlyYSIsInZhbHVlcyI6WyIxIl19XX0seyJyZXBvX3BhdGgiOiJleGFtcGxlLXJlcG8tbG9jYWwvYWNoYW5nZS9TY3JlZW4gU2hvdCAyMDE4LTA0LTA1IGF0IDEwLjQ3LjE2ICgyKS5wbmciLCJjaGVja3N1bSI6IjIzMzY2Mzk5N2EyZGYxY2FmZDZhZWI1NjkxNjZhZjkxZjYzZDQwZjRmNDFiNjgxY2JlN2RmMjlkMWE1YzE3MGEiLCJwcm9wcyI6W3sia2V5IjoiamlyYSIsInZhbHVlcyI6WyIxIl19XX0seyJyZXBvX3BhdGgiOiJleGFtcGxlLXJlcG8tbG9jYWwvYWNoYW5nZS9TY3JlZW4gU2hvdCAyMDE4LTA0LTA1IGF0IDEwLjQ3LjE2IDEucG5nIiwiY2hlY2tzdW0iOiI1YTczMGIwMWU4MWUyYWEzYjUxODhiY2VmM2JlOGU0ZTdkNjFmODNiNjE1NmIyMmEzM2M5YTNmMjNmZjM4ZTE5IiwicHJvcHMiOlt7ImtleSI6ImppcmEiLCJ2YWx1ZXMiOlsiMSJdfV19LHsicmVwb19wYXRoIjoiZXhhbXBsZS1yZXBvLWxvY2FsL2FjaGFuZ2UvU2NyZWVuIFNob3QgMjAxOC0wNC0wNSBhdCAxMC40Ny4xNiAoMykucG5nIiwiY2hlY2tzdW0iOiJjYmZjZjk0NzkzYzQ1ZTk5NmY2YTQxODY5M2ZjYjBhZDU1NzRkMzJiYzUwN2NjNmVjMDAzMDkxMmFjMWQ3MDUzIiwicHJvcHMiOlt7ImtleSI6ImppcmEiLCJ2YWx1ZXMiOlsiMSJdfV19XX0.QWzTD2uXhLw5FW1483qEYA_h47jak8YE24mLwuF1UcT9yTYZBdEMrFWTz0uZVrPtlqi65Ek6oNeSFZO657sjpuTOpfPIg053nxOoIa4mxlxMS5nCM50Xj3qobcll0P_sX8Il8AGWbX9oI9HvSGAKYbxmu-3kVs0W1tCacb_VuHsL5KkgY2Thq5dBKhQ73aS1cE-CnFobQKGcsx10eFhEFV8VbajGLpKV8nhERDE4XA5oRARA-CczLlEYNnvn5aRD-Q1n5yI7Cys8hoDIxDLT2OCQ5alb9h4D4w7mGJrtQG0xNWsstGOTSL1HLXAe27qvBxCIsp6afX675AkOs1Eg0g


Delete All Versions of Release Bundle By Name 

Description: Deletes or archives all versions of a release bundle. Release bundle versions will also be deleted from their's source Artifactory, if they exist, and archive flag is set to false.

Since: 1.0
Security:  Authenticated users only. User must have delete permission for the release bundle.
Usage: DELETE /api/v1/release_bundle/:name[?archive=true]
Request headers: N/A
Consumes: N/A


Request Example
$ curl -XDELETE -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/release_bundle/bundle1?archive=false"


Response status codes:

204 - Successfully deleted / archived release bundle versions
404 - Release bundle not found

Response headers: N/A

Produces: N/A

Delete Release Bundle Version

Description: Deletes or archives specific release bundle version. Release bundle versions will also be deleted from their's source Artifactory, if they exist, and archive flag is set to false.

Since: 1.0
Security:  Authenticated users only. User must have delete permission for the release bundle.
Usage: DELETE /api/v1/release_bundle/:name/:version[?archive=true]
Request headers: N/A
Consumes: N/A


Request Example
$ curl -XDELETE -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/release_bundle/bundle1/1.0.0?archive=false"


Response status codes:

204 - Successfully deleted / archived release bundle version
404 - Release bundle or release bundle version not found

Response headers: N/A

Produces: N/A


DISTRIBUTION

Distribute Release Bundle Version to Artifactory Instances

Description: Schedules a release bundle version for distribution to Artifactory instances available from Mission Control. Distribution tracking id will be returned.

Since: 1.0
Security: Authenticated users only. User must have distribution permission for the release bundle. The destination instances will be filtered by the user's permissions.
Usage: POST /api/v1/distribution/:name/:version
Request headers: N/A
Consumes: application/json


distribute.json
{
  "dry_run": true|false,
  "distribution_rules": [
    {
      "service_name": "?wildcard*",
      "site_name": "?wildcard*",
      "city_name": "?wildcard*",
      "country_codes": ["?wildcard*"]
    }
  ]
}
FieldTypeRequiredDefault ValueDescription
dry_run
Booleannotrue 
If true, only parses and validates
distribution_rules
List (Object)yesN/A Describes the filters by which destination Artifactory instances are selected. Must resolve at least one instance.
distribution_rules.service_name
Stringno"*"Wildcard filter for service name
distribution_rules.site_name
Stringno"*" Wildcard filter for site name
distribution_rules.city_name
Stringno"*" Wildcard filter for site city name
distribution_rules.country_codes
List (String)no[ "*" ] Wildcard filters for site country codes

 


Request Example
$ curl -XPOST -u admin:password "http://localhost:8080/api/v1/distribution/bundle1/1.0" -T distribute.json

 

Response status codes:

200 - Success for dry_run
202 - Successfully scheduled distribution

400 - Release bundle version must be signed before distribution

404 - Release bundle or release bundle version not found

Response headers: N/A

Produces: application/json


Response
{
  "id": 188527534551203840,
  "sites": [
    {
      "service_id": "jfrt@01cc8hkzy1zgtc1wqw3zk41p2a",
      "name": "US_NY_Art01",
      "type": "edge"
    },
    ...
  ]
}


Stop Release Bundle Version Distribution

Description: Stop a release bundle version distribution to Artifactory instances.

Since: 1.1
Security: Authenticated users only. User must have distribution permission for the release bundle. The destination instances will be filtered by the user's permissions.
Usage: PUT /api/v1/distribution/:name/:version/abort
Request headers: N/A
Consumes: application/json


Request Example
$ curl -XPUT -u admin:password "http://localhost:8080/api/v1/distribution/bundle1/1.0/abort"

 

Response status codes:

202 - Successfully scheduled distribution interruption. Returns the list of Artifactory instances affected by the stop request.

204 - No Artifactory instance with distribution in progress found
404 - Release bundle or release bundle version not found

Response headers: N/A

Produces: application/json


Response
[
    {
        "name":"US_NY_Art01",
        "service_id":"jfrt@01cejrg5ack7dd1v3r213a0vx9",
        "type":"edge"
    },
    {
        "name":"UK_LN_Art02",
        "service_id":"jfrt@01cejrfwjtt65d1g9asq8h1cda",
        "type":"edge"
    }
]


Delete Release Bundle Version from Artifactory Instances

Description: Schedules a release bundle version for deletion in Artifactory instances available from Mission Control. Distribution tracking id will be returned.

Since: 1.0
Security: Authenticated users only. User must have distribution delete permission for the release bundle. The destination instances will be filtered by the user's permissions.
Usage: POST /api/v1/distribution/:name/:version/delete
Request headers: N/A
Consumes: application/json


delete.json
{
  "dry_run": true|false,
  "distribution_rules": [
    {
      "service_name": "?wildcard*",
      "site_name": "?wildcard*",
      "city_name": "?wildcard*",
      "country_codes": ["?wildcard*"]
    }
  ],
  "on_success": "keep|delete|archive"
}
FieldTypeRequiredDefault ValueDescription
dry_run
Booleannotrue 
If true, only parses and validates
distribution_rules
List (Object)yesN/A Describes the filters by which destination Artifactory instances are selected. Must resolve at least one instance.
distribution_rules.service_name
Stringno"*"Wildcard filter for service name (Artifactory instance name as configured in Mission Control)
distribution_rules.site_name
Stringno"*" Wildcard filter for site name
distribution_rules.city_name
Stringno"*" Wildcard filter for site city name
distribution_rules.country_codes
List (String)no[ "*" ] Wildcard filters for site country codes
on_success
StringnokeepLocal action to be performed on the release bundle versions after deletion is complete in the specified Artifactory instances.

 


Request Example
$ curl -XPOST -u admin:password "http://localhost:8080/api/v1/distribution/bundle1/1.0/delete" -T delete.json

 

Response status codes:

200 - Success for dry_run
202 - Successfully scheduled deletion
404 - Release bundle or release bundle version not found

Response headers: N/A

Produces: application/json


Response
{
  "id": 188527534551203840,
  "sites": [
    {
      "service_id": "jfrt@01cc8hkzy1zgtc1wqw3zk41p2a",
      "name": "US_NY_Art01",
      "type": "edge"
    },
    ...
  ]
}


Get Distribution Status Details

Description:  Get status details for all distributions.

Since: 1.0
Security: Authenticated users only. Only distributions of release bundles which the user has read permission for are displayed.
Usage: GET api/v1/release_bundle/distribution
Request Headers: N/A

Consumes: N/A

Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/release_bundle/distribution"


Response status codes:

200 - Success

Response headers: N/A

Produces: application/json


Response
[
  {
    "distribution_id": 188527534551203840,
    "distribution_friendly_id": 1,
    "type": "distribute | delete_release_bundle_version",
    "release_bundle_name": "release-bundle",
    "release_bundle_version": "1.0.0",
    "status": "Not distributed | In progress | Completed | Failed",
    "distribution_rules": [
      {
        "site_name": "*",
        "city_name": "*",
        "country_codes": ["*"],
        "service_name": "*"
      },
      ...
    ],
    "source_artifactory": {
      "service_id": "jfrt@01cc8hm002py3z1y5yq5t90xrt",
      "name": "DEV_Art01",
      "type": "artifactory"
    },
    "sites": [
      {
        "status": "Not distributed | In progress | Completed | Failed",
        "target_artifactory": {
          "service_id": "jfrt@01cc8hkzy1zgtc1wqw3zk41p2a",
          "name": "US_NY_Art01",
          "type": "edge"
        },
        "total_files": 4,
        "total_bytes": 4403784,
        "distributed_bytes": 0,
        "distributed_files": 0,
        "general_error": "",
        "file_errors": [],
        "files_in_progress": []
      },
      ...
    ]
  },
  ...
]

Get Distribution Status Details by Release Bundle Name

Description:  Get status details for all distributions of all versions of a release bundle.

Since: 1.0
Security: Authenticated users only. User must have read permission for the release bundle.
Usage: GET api/v1/release_bundle/:name/distribution
Request Headers: N/A

Consumes: N/A

 

Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/release_bundle/bundle1/distribution"


Response status codes:

200 - Success

Response headers: N/A

Produces: application/json


Response
[
  {
    "distribution_id": 188527534551203840,
    "distribution_friendly_id": 1,    
    "type": "distribute | delete_release_bundle_version",
    "release_bundle_name": "release-bundle",
    "release_bundle_version": "1.0.0",
    "status": "Not distributed | In progress | Completed | Failed",
    "distribution_rules": [
      {
        "site_name": "*",
        "city_name": "*",
        "country_codes": ["*"],
        "service_name": "*"
      },
      ...
    ],
    "source_artifactory": {
      "service_id": "jfrt@01cc8hm002py3z1y5yq5t90xrt",
      "name": "DEV_Art01",
      "type": "artifactory"
    },
    "sites": [
      {
        "status": "Not distributed | In progress | Completed | Failed",
        "target_artifactory": {
          "service_id": "jfrt@01cc8hkzy1zgtc1wqw3zk41p2a",
          "name": "US_NY_Art01",
          "type": "edge"
        },
        "total_files": 4,
        "total_bytes": 4403784,
        "distributed_bytes": 0,
        "distributed_files": 0,
        "general_error": "",
        "file_errors": [],
        "files_in_progress": []
      },
      ...
    ]
  },
  ...
]


Get Distribution Status Details by Release Bundle Version

Description:  Get status details for all distributions of a specific release bundle version.

Since: 1.0
Security: Authenticated users only. User must have read permission for the release bundle.
Usage: GET api/v1/release_bundle/:name/:version/distribution
Request Headers: N/A

Consumes: N/A


Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/release_bundle/bundle1/1.0/distribution"


Response status codes:

200 - Success

Response headers: N/A

Produces: application/json


Response
[
  {
    "distribution_id": 188527534551203840,
    "distribution_friendly_id": 1,
    "type": "distribute | delete_release_bundle_version",
    "release_bundle_name": "release-bundle",
    "release_bundle_version": "1.0.0",
    "status": "Not distributed | In progress | Completed | Failed",
    "distribution_rules": [
      {
        "site_name": "*",
        "city_name": "*",
        "country_codes": ["*"],
        "service_name": "*"
      },
      ...
    ],
    "source_artifactory": {
      "service_id": "jfrt@01cc8hm002py3z1y5yq5t90xrt",
      "name": "DEV_Art01",
      "type": "artifactory"
    },
    "sites": [
      {
        "status": "Not distributed | In progress | Completed | Failed",
        "target_artifactory": {
          "service_id": "jfrt@01cc8hkzy1zgtc1wqw3zk41p2a",
          "name": "US_NY_Art01",
          "type": "edge"
        },
        "total_files": 4,
        "total_bytes": 4403784,
        "distributed_bytes": 0,
        "distributed_files": 0,
        "general_error": "",
        "file_errors": [],
        "files_in_progress": []
      },
      ...
    ]
  },
  ...
]

  

Get Distribution Status Details by Tracker Id

Description:  Get status details for a specific distribution.

Since: 1.0
Security: Authenticated users only. User must have read permission for the release bundle.
Usage: GET api/v1/release_bundle/:name/:version/distribution/:tracker_id
Request Headers: N/A

Consumes: N/A

 

$ curl -XGET -u admin:password "http://localhost:8080/api/v1/release_bundle/bundle1/1.0/distribution/188527534551203840"

 

Response status codes:

200 - Success

Response headers: N/A

Produces: application/json


Response
{
  "distribution_id": 188527534551203840,
  "distribution_friendly_id": 1,
  "type": "distribute | delete_release_bundle_version",
  "release_bundle_name": "release-bundle",
  "release_bundle_version": "1.0.0",
  "status": "Not distributed | In progress | Completed | Failed",
  "distribution_rules": [
    {
      "site_name": "*",
      "city_name": "*",
      "country_codes": ["*"],
      "service_name": "*"
    },
    ...
  ],
  "source_artifactory": {
    "service_id": "jfrt@01cc8hm002py3z1y5yq5t90xrt",
    "name": "DEV_Art01",
    "type": "artifactory"
  },
  "sites": [
    {
      "status": "Not distributed | In progress | Completed | Failed",
      "target_artifactory": {
        "service_id": "jfrt@01cc8hkzy1zgtc1wqw3zk41p2a",
        "name": "US_NY_Art01",
        "type": "edge"
      },
      "total_files": 4,
      "total_bytes": 4403784,
      "distributed_bytes": 0,
      "distributed_files": 0,
      "general_error": "",
      "file_errors": [],
      "files_in_progress": []
    },
    ...
  ]
}


TOKEN MANAGEMENT

Create a Token

Description: Creates an authentication token for an existing (non-transient) user.

Since: 1.2
Security: admin for itself and others (or with admin scope), user for itself only
Usage: POST /api/v1/security/token
Request Headers: N/A
Consumes: application/x-www-form-urlencoded


FieldTypeRequiredDefault ValueDescription
grant_typeStringnoclient_credentialsThe grant type used to authenticate the request. In this case, the only value supported is "client_credentials" which is also the default value if this parameter is not specified.
usernameStringyes
The user name for which this token is created. Non-admin users can only create tokens for themselves so they must specify their own username.
scopeStringno
The scope to assign to the token provided as a space-separated list of scope tokens. Currently there are only one possible scope option:
applied-permissions/admin
expires_inLongno0

The time in seconds for which the token will be valid. To specify a token that never expires, set to zero.

refreshableBooleannofalseIf true, this token is refreshable and the refresh token can be used to replace it with a new token once it expires.
$ curl -XPOST -u admin:password http://localhost:8080/api/v1/security/token -d 'username=user' -d 'refreshable=true' -d 'scope=applied-permissions%2Fadmin' -d "expires_in=123"


Response status codes:

201 - Successfully created token

Response headers: N/A

Produces: application/json


Response
 {
	"access_token": "eyJ2ZXIiOiIyIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJ6WWFWQjVFRlpkOXlpbWtCNkZTbDAtSWFhMHRPWldLX293c1BTVTNTZmdNIn0.eyJzdWIiOiJsZW5vbiIsInNjcCI6ImFwcGxpZWQtcGVybWlzc2lvbnNcL2FkbWluIiwiYXVkIjoiamZkc0AwMWNoMDV0ajRuM3NzODBzNm4zdjIzMDdiOSIsImlzcyI6ImpmZHNAMDFjaDA1dGo0bjNzczgwczZuM3YyMzA3YjkiLCJleHAiOjE1MzAwOTk2MTgsImlhdCI6MTUzMDA5OTQ5NSwianRpIjoiYTQzM2YwZDAtNTQ5OC00YjI5LWE5ODctZjI3MTNkYmMyOTdmIn0.E7csEhcHqsOJxz1jmhDVu_Ij51yQyxYifMXusexqZk78pi_7YHlJcY1iRg6VMthdv8_Db2CsaNzYdubCyTTt77OOTSVfqJdZsm_0AEz-paIj71lvgyJBFLZ2bjE253tMGLgweypUqqEsEH3J3FyfAaw4XXURlKT5inbwKklMu-DvPG5772ZS1Y6YPU8oOGc2dWg_BHUvjMTJ5vQAw0Ws5Ta2CJ0DF40JLQKcyN_JCgzQ2RCXr2C70JIF9Fa0OBaIKVT-DguSNGU83dnr-YF0XBsUcTDu5K-Jl5H3FMdb129awXe4_fLLdltMK8iAaRujsIDlvexdlezVal4nLRZcxA",
	"refresh_token": "f96bda0c-ab50-4b7e-96f1-be8bd20605a3",
	"expires_in": 123,
	"scope": "applied-permissions/admin",
	"token_type": "Bearer"
}

Refresh a Token


Description: Refreshes the authentication token for an existing (non-transient) user.
Since: 1.2
Security: admin for itself and others (or with admin scope), user for itself onlya
Usage: POST /api/v1/security/token
Request Headers: N/A
Consumes: application/x-www-form-urlencoded


FieldTypeRequiredDefault ValueDescription
grant_typeStringyes
The grant type used to authenticate the request. In this case, the only value supported is "refresh_token".
access_tokenStringyes
The access token to refresh.
refresh_tokenStringyes
The refresh token of the access token that needs to be refreshed.
expires_inLongno0

The time in seconds for which the token will be valid. To specify a token that never expires, set to zero.

refreshableBooleannotrueIf true, this token is refreshable and the refresh token can be used to replace it with a new token once it expires.
$ curl -XPOST -u admin:password http://localhost:8080/api/v1/security/token -d "grant_type=refresh_token" -d "refresh_token=fgsg53t3g…" -d "access_token=gsfdgw35gt..."


Response status codes:

200 - Successfully refreshed token

Response headers: N/A

Produces: application/json


Response
 {
	"access_token": "eyJ2ZXIiOiIyIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJ6WWFWQjVFRlpkOXlpbWtCNkZTbDAtSWFhMHRPWldLX293c1BTVTNTZmdNIn0.eyJzdWIiOiJsZW5vbiIsInNjcCI6ImFwcGxpZWQtcGVybWlzc2lvbnNcL2FkbWluIiwiYXVkIjoiamZkc0AwMWNoMDV0ajRuM3NzODBzNm4zdjIzMDdiOSIsImlzcyI6ImpmZHNAMDFjaDA1dGo0bjNzczgwczZuM3YyMzA3YjkiLCJleHAiOjE1MzAwOTk2MTgsImlhdCI6MTUzMDA5OTQ5NSwianRpIjoiYTQzM2YwZDAtNTQ5OC00YjI5LWE5ODctZjI3MTNkYmMyOTdmIn0.E7csEhcHqsOJxz1jmhDVu_Ij51yQyxYifMXusexqZk78pi_7YHlJcY1iRg6VMthdv8_Db2CsaNzYdubCyTTt77OOTSVfqJdZsm_0AEz-paIj71lvgyJBFLZ2bjE253tMGLgweypUqqEsEH3J3FyfAaw4XXURlKT5inbwKklMu-DvPG5772ZS1Y6YPU8oOGc2dWg_BHUvjMTJ5vQAw0Ws5Ta2CJ0DF40JLQKcyN_JCgzQ2RCXr2C70JIF9Fa0OBaIKVT-DguSNGU83dnr-YF0XBsUcTDu5K-Jl5H3FMdb129awXe4_fLLdltMK8iAaRujsIDlvexdlezVal4nLRZcxA",
	"refresh_token": "f96bda0c-ab50-4b7e-96f1-be8bd20605a3",
	"expires_in": 123,
	"scope": "applied-permissions/admin",
	"token_type": "Bearer"
}


Revoke a Token

Description: Revokes an access token by specifying the token or the token_id

Since: 1.2
Security: Admin
Usage: POST /api/v1/security/token/revoke
Request Headers: N/A
Consumes: application/x-www-form-urlencoded


FieldTypeRequiredDescription
tokenStringyes (if token_id is empty)The token to be revoked. Must not be specified if token_id specified.
token_id
Stringyes (if token is empty)The ID of the token to be revoked. Must not be specified if token specified.
$ curl -u admin:password -XPOST "http://localhost:8080/api/v1/security/token/revoke" -d "token=fasdt3..."

or

$ curl -u admin:password -XPOST "http://localhost:8080/api/v1/security/token/revoke" -d "token_id=7e0eec..."


Response status codes:

200 - Successfully revoked token
404 - Token not found


Get Tokens Info

Description: Gets a list of access tokens by user.

Since: 1.2
Security: Admin
Usage: GET /api/v1/security/token


$ curl -u admin:password -XGET "http://localhost:8080/api/v1/security/token"


Response status codes:

200 - Successfully retrieves a list of tokens
404 - Tokens not found
Response headers: N/A

Produces: application/json


Response
{
	"tokens": [
		{
			"token_id": "58ae2b6f-085d-493e-b7c3-670d7700c034",
			"issuer": "jfds@01ch05tj4n3ss80s6n3v2307b9",
			"subject": "admin",
			"issued_at": 1530088236,
			"expiry": 2476168236,
			"refreshable": false
		},
		{
			"token_id": "5c0399f9-de42-4cc8-bbd6-ba04a8b861a7",
			"issuer": "jfds@01ch05tj4n3ss80s6n3v2307b9",
			"subject": "lenon",
			"issued_at": 1530089226,
			"refreshable": true
		}
	]
}


PERMISSION MANAGEMENT

Permissions types:

r

read

w

write

d

delete

x

distribute

m

manage/admin

  

Set Permissions by Name

Permissions can be created and overridden by specifying the unique permission name.

Description: Set permissions for users and groups, based on permission scope. The response body will contain the created/updated permission.

Since: 1.0
Security: Admin only.
Usage: PUT /api/v1/security/permissions/:name
Request Headers: N/A
Consumes: application/json


$ curl -XPUT -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/security/permissions/permission-name" -T permission.json


Response status codes:

200 - Successfully set permission

Response headers: N/A

Produces: application/json

This section is divided into segments to elaborate on the structure of the different permission scopes.

Set Permissions for service scope

The service scope is used to define service administration permissions.

Allowed actions for service scope: m.

Only one service scope permission is allowed. The unique name for this permission is "service".


service.json
{
  "scope": "service",
  "principals": {
    "users": {
      "admin": ["m"]
    },
    "groups": {
	  "admins": ["m"]
    }
  }
}

   

Set permissions for release bundles scope

The release_bundles scope is used to define permissions for release bundle interactions.

Allowed actions for release_bundles scope: r, w, d, x .

The permissions are applied to release bundles which names are matched by the passed wildcard expressions.

Multiple release_bundles scope permissions are allowed.


release_bundles.json
{
  "scope": "release_bundles",
  "release_bundles": ["?wildcard*","?wildcard*"],
  "principals": {
	"users": {
	  "distributor1": ["r","w","d","x"]
	},
	"groups": {
      "distributors1": ["r","x"]
    }
  }
}


Set permissions for distribution sites scope

The distribution_sites scope is used to define permissions for interactions with Artifactory instances, such as distributing and deleting release bundles.

Allowed actions for distribution_sites scope: x, d.

The permissions are applied to Artifactory instances available from Mission Control which information is matched by the passed wildcard expressions.

Multiple distribution_sites scope permissions are allowed.


distribution_sites.json
{
  "name": "distribution-permission",
  "scope": "distribution_sites",
  "distribution_destinations": [
	{
      "service_name": "*",
	  "site_name": "*",
      "city_name": "*",
      "country_codes": ["*"]
	}
  ],
  "principals": {
	"users": {
	  "distributor1": ["x","d"]
	},
	"groups": {
	  "distributors1": ["x"]
    }
  }
}

  

Get All Permissions

Description: Get all permissions.

Since: 1.0
Security: Admin only.
Request Headers: N/A

Consumes: N/A


Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/security/permissions"


Response status codes:

200 - Success

Response headers: N/A

Produces: application/json


Response
[
  {
    "name": "service",
	"scope": "service",
	"principals": {
	  "users": {
	    "admin": ["m"],
        ...
	  },
	  "groups": {
	    "admins": ["m"],
        ...
      }
	}
  },
  {
	"name": "bundle-permission",
    "scope": "release_bundles",
    "release_bundles": ["?wildcard*","?wildcard*"],
    "principals": {
	  "users": {
	    "distributor1": ["r","w","d","x"],
		...
	  },
	  "groups": {
        "distributors1": ["r","x"],
        ...
      }
	}
  },
  {
    "name": "distribution-permission",
    "scope": "distribution_sites",
    "distribution_destinations": [
	  {
   		"service_name": "*",
	    "site_name": "*",
		"city_name": "*",
        "country_codes": ["*"]
	  },
      ...
	],
	"principals": {
	  "users": {
	    "distributor1": ["x","d"],
		...
	  },
	  "groups": {
	    "distributors1": ["x"],
        ...
	  }
    }
  },
  ...
]

Get Permission by Name

Description: Get permission information by name.

Since: 1.0
Security: Admin only.
Usage: GET /api/v1/security/permissions/:name
Request Headers: N/A
Consumes: N/A

  


Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/security/permissions/bundle-permission"


Response status codes:

200 - Success
404 - Permission not found

Response headers: N/A

Produces: application/json


Response
{
  "name": "bundle-permission",
  "scope": "release_bundles",
  "release_bundles": ["?wildcard*","?wildcard*"],
  "principals": {
    "users": {
	  "distributor1": ["r","w","d","x"],
	  ...
	},
	"groups": {
      "distributors1": ["r","x"],
      ...
    }
  }
}

Delete Permission

Description: Deletes the permission. Permission with service scope cannot be deleted.

Since: 1.0
Security: Admin only.
Usage: DELETE /api/v1/security/permissions/:name
Request Headers: N/A
Consumes: N/A


$ curl -XDELETE -u admin:password "http://localhost:8080/api/v1/security/permissions/permission-name"


Response status codes:

204 - Successfully deleted permission
404 - Permission not found

Response headers: N/A

Produces: N/A

SUPPORT

Create Support Bundle

Description: Creates support bundle 
Since: 1.6
Security: Admin only
Usage: POST  /api/v1/system/support/bundle
Request headers: N/A
Consumes: application/json
Produces: application/json

create_support_bundle.json
{
 "parameters": {
                "configuration": true|false,
                "logs": {
                         "include":  true|false,
                         "start_date": ISO8601 based date in the pattern: YYYY-MM-DD,
                         "end_date": ISO8601 based date in the pattern: YYYY-MM-DD,
                        },
                "system": true|false,
                "thread_dump": {
                                "count": 1,
                                "interval" :0
                               }
                    },
  "description": "",
  "name": ""
}
FieldTypeRequiredDefault ValueSinceDescription
parameters

Object

no

N/A

1.6

Support bundle parameters

parameters.configuration

Boolean

no

true

1.6

Collect configuration files

parameters.logs

Object

no

N/A

1.6

Collect all system logs, if this field is not specified support bundle will collect logs from day before today until today.

parameters.logs.include

Boolean

no

true

1.6

Collect system logs.

parameters.logs.start_date

String

no

Day before end_date

1.6

Start date from which to fetch the logs
parameters.logs.end_date
StringnoToday1.6End date until which to fetch the logs
system

Boolean

no

true

1.6

Information about your system including storage, system properties, cpu, and JVM information
thread_dump

Object

no

N/A

1.6

Create a thread dump for all running threads
thread_dump.count

Integer

no

1

1.6

Number of thread dumps to collect


thread_dump.interval

Integer

no

0


1.6

Interval between times of collect thread dump in milliseconds


description

String

no

N/A

1.6

Support bundle description


name
StringnoN/A1.6Support bundle name
Request Example
$ curl -XPOST -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/system/support/bundle" -T create_support_bundle.json

Response status codes:
200 - Successfully create support bundle

Response headers: N/A
Produces: application/json

response.json
{
 "id": 20181230145474-53666747,
  "artifactory": { 
                 "service_id": "jfds@...",
                 "bundle_url":
                      http://<artifactory host>:<artifactory port>/artifactory/support-bundles/<bundle id>/jfds/<service id>
                 }
}

Create Specific Support Bundle

Description: Creates a new support bundle and assigns it a specific ID
Since: 1.6
Security: Admin only
Usage: PUT  /api/v1/system/support/bundle/:bundle_id
Request headers: N/A
Consumes: application/json
Produces: application/json

create_support_bundle.json
{
 "parameters": {
                "configuration": true|false,
                "logs": {
                         "include":  true|false,
                         "start_date": ISO8601 based date in the pattern: YYYY-MM-DD,
                         "end_date": ISO8601 based date in the pattern: YYYY-MM-DD,
                        },
                "system": true|false,
                "thread_dump": {
                                "count": 1,
                                "interval" :0
                               }
                    },
  "description": "",
  "name": ""
}
FieldTypeRequiredDefault ValueSinceDescription
parameters

Object

no

N/A

1.6

Support bundle parameters

parameters.configuration

Boolean

no

true

1.6

Collect configuration files

parameters.logs

Object

no

N/A

1.6

Collect all system logs, if this field is not specified support bundle will collect logs from day before today until today.

parameters.logs.include

Boolean

no

true

1.6

Collect system logs.

parameters.logs.start_date

String

no

Day before end_date

1.6

Start date from which to fetch the logs
parameters.logs.end_date
StringnoToday1.6End date until which to fetch the logs
system

Boolean

no

true

1.6

Information about your system including storage, system properties, cpu, and JVM information
thread_dump

Object

no

N/A

1.6

Create a thread dump for all running threads
thread_dump.count

Integer

no

1

1.6

Number of thread dumps to collect


thread_dump.interval

Integer

no

0


1.6

Interval between times of collect thread dump in milliseconds


description

String

no

N/A

1.6

Support bundle description


name
StringnoN/A1.6Support bundle name
Request Example
$ curl -XPUT -u admin:password -H "Content-Type: application/json" "http://localhost:8080/api/v1/system/support/bundle/{bundle_id}" -T create_support_bundle.json

Response status codes:

200 - Successfully create support bundle
400 - Corresponding repository does not exist in Artifactory. Support bundle will be persisted to the file system in each Distribution node.
404 - Artifactory authentication provider could not be found
Response headers: N/A
Produces: application/json

response.json
{
 "id": 20181230145474-53666747,
  "artifactory": { 
                 "service_id": "jfds@...",
                 "bundle_url":
                      http://<artifactory host>:<artifactory port>/artifactory/support-bundles/<bundle id>/jfds/<service id>
                 }
}

Get Support Bundle Info

Description: get support bundle information
Since: 1.6
Security: Admin only
Usage: GET  /api/v1/system/support/bundle/:bundle_id
Request headers: N/A
Consumes: N/A

Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/system/support/bundle/{bundle_id}"
info_support_bundle.json
{
 "parameters": {
                "configuration": true,
                "logs": {
                         "include":  true,
                         "start_date": 2019-01-20,
                         "end_date": 2019-01-21
                        },
                "system": true,
                "thread_dump": {
                                "count": 2,
                                "interval": 100
                               }
                    },
  "description": "",
  "name": ""
  "artifactory": {
                 "service_id": "",
                 "bundle_url": 
                      http://<artifactory host>:<artifactory port>/artifactory/support-bundles/<bundle id>/jfds/<service id>
                 }
  },
  status: success,
  created:  2019-02-02,
}

Response status codes:

200 - Successfully get support bundle info
404 - Support bundle not found
Response headers: N/A
Produces: application/json

Get support bundle

Description: download support bundle
Since: 1.6
Security: Admin only
Usage: GET  /api/v1/system/support/bundle/:bundle_id/archive
Request headers: N/A
Consumes: N/A

Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/system/support/bundle/{bundle_id}/archive"
response.json
200 OK
Content-Type: application/zip


Response status codes:
200 - Successfully download support bundle
404 - Support bundle not found
Response headers: N/A

Delete Support Bundle

Description: delete support bundle
Since: 1.6
Security: Admin only
Usage: DELETE  /api/v1/system/support/bundle/:bundle_id
Request headers: N/A
Consumes: N/A

Request Example
$ curl -XDELETE -u admin:password "http://localhost:8080/api/v1/system/support/bundle/{bundle_id}"
response.json
204 No Content

Response status codes:

204 - Successfully delete support bundle
404 - Support bundle not found
Response headers: N/A

List Support Bundles

Description: 
get the list of all support bundles
Since: 1.6
Security: Admin only
Usage: GET  /api/v1/system/support/bundles
Request headers: N/A
Consumes: N/A

Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/system/support/bundles"
response.json
{
  "count": 2,
  "bundles": [
    {
      id: 20181230145474-53666747,
      description: "",
      name: "",
      created:  2018-12-30,
    },
    ….
  ]
}

Response status codes:

200 - Success
Response headers: N/A

MAINTENANCE

Generate Stop All Tasks token 

Description: Generates an execution token to stop all distribution tasks. This key is used with the Stop All Tasks REST API.
Since: 1.8.1
Security: Admin only
Usage: GET  /api/v1/maintenance/generate_token/stop_all
Request headers: N/A
Consumes: application/json
Produces: application/json

Request Example
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/maintenance/generate_token/stop_all"
response.json
{
  "token":"JEv4CnrZNhmgtkRV9aKmGsrozGEoaoBs3okv9SFusdhR3hUKiWdKwAhoeP1SLEy8hFZqFhE"
}


Response status codes:

200 - Success

Stop All Tasks

Description: Aborts all running distribution tasks. Requires an execution token.
Since: 1.8.1
Security: Admin only
Usage: POST  /api/v1/maintenance/execute/stop_all/:token
Request headers: N/A
Consumes: application/json
Produces: application/json

Request Example
$ curl -XPOST -u admin:password "http://localhost:8080/api/v1/maintenance/execute/stop_all/{token}?dryRun=false"
FieldTypeRequiredDefault ValueSinceDescription
dryRun

Query Param

yes

true

1.8.1

If true, only parses and validates.

response.json
{
  "trackers_db_info": {
    "affected_edge_tracker_artifacts": 8,
    "affected_edge_trackers": 1,
    "affected_trackers": 1
  },
  "tasks_queue_flushed": true
}

Response status codes:

202 - Successfully aborted all distribution tasks

Response headers: N/A

ERROR RESPONSES

Status codeReasonSuggested actions
400Invalid request parameters (headers / body)Compare request against specification
401Endpoint requires authenticationRepeat request with authentication credentials
403Endpoint permission requirements are not metResponse will include necessary permissions
500Unexpected error during request handlingCheck distribution logs

JFrog.com | Documentation | Featured | Have a question? Want to report an issue? Contact JFrog support