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
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/settings"
Response status codes:
200 - Success
Response headers: N/A
Produces: application/json
{ "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
$ curl -u user:password -H "Accept: application/json" -H "Content-Type: application/json" -X POST "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/settings" -T system_settings.json
{ "call_home_enabled": true }
Field | Type | Required | Default Value | Since | Description |
---|---|---|---|---|---|
call_home_enabled | Boolean | no | false | 1.6 | If enabled, sending usage statistics to JFrog |
Response status codes:
200 - Success
SIGNING KEYS
Upload and Propagate GPG Signing Keys for Distribution
Description: GPG Keys are used to sign Release Bundles. The GPG key pair will automatically be propagated to Artifactory Source and Destinations. You can use this to do one of the following:
- Upload a GPG key pair to JFrog Distribution from your file system
- Retrieve keys from a vault.
Notes:
- Requires JFrog Mission Control version 4.5.0 and above.
- Distribution relies on JFrog Mission Control communicating to the JPDs to propagate the GPG Keys
- The keys must be copied and pasted into the request body.
- You cannot use
public_key
andprivate_key
paramaters with thevault_data
parameter. - The
vault_id
parameter should be Hashicorp as it is the only supported vault for now.
Since: 2.4
From version 2.8.1, Distribution supports managing multiple GPG signing keys to sign Release Bundles. This enables you to assign a signing key pair per Release Bundle providing you with the granularity to choose which keys to use to sign the Release Bundles instead of using the same key pair to sign all.
Security: Admin only
Usage: POST /api/v1/keys/{protocol: pgp|gpg}
Request headers: N/A
Consumes: application/json
The JSON request body should have "set_as_default": true
if this is the first key that is set or if there is no default key in Artifactory.
POST:/api/v1/keys/{protocol: pgp|gpg} body: { "key": { "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----...-----END PGP PUBLIC KEY BLOCK-----", "private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----...-----END PGP PRIVATE KEY BLOCK-----" }, "propagate_to_edge_nodes": true, "fail_on_propagation_failure": false } Expected response: { "report": { "message" : "error message if exists" "status" : PARTIAL_SUCCESS | SUCCESS | FAILURE | PROPAGATION_NOT_REQUESTED | PROPAGATION_NOT_SUPPORTED_BY_MISSION_CONTROL | NO_GPG_KEY_TO_PROPAGATE "details" : [ { "jpd_id" : "id1", "name" : "US-EAST" "key_alias" : "my first key" "status" : "SUCCESS" }, { "jpd_id" : "id2", "name" : "US-WEST" "key_alias" : "my first key" "status" : "SUCCESS" }, ] } }
{ "key": { "alias": "name", "public_key" : "", "private_key": "" }, "propagate_to_edge_nodes" : false, "fail_on_propagation_failure": false, "set_as_default": true }
body: { "fail_on_propagation_failure": false, "propagate_to_edge_nodes": false, "key": { "vault_data": { "vault_id": "hashicorp", "public_key": { "path": "kv/public/path", "key": "public" }, "private_key": { "path": "kv/private/path", "key": "private" } Expected response: { "report": { "message" : "error message if exists" "status" : PARTIAL_SUCCESS | SUCCESS | FAILURE | PROPAGATION_NOT_REQUESTED | PROPAGATION_NOT_SUPPORTED_BY_MISSION_CONTROL | NO_GPG_KEY_TO_PROPAGATE "details" : [ { "jpd_id" : "id1", "name" : "US-EAST" "key_alias" : "my first key" "status" : "SUCCESS" }, { "jpd_id" : "id2", "name" : "US-WEST" "key_alias" : "my first key" "status" : "SUCCESS" }, ] } }
Update Alias Name
Description: Updates the Alias name.
Since: 2.8.1
Security: Admin only
Usage: PUT keys/gpg/{alias_name}
Request headers: N/A
Consumes: application/json
{ "new_alias": {} }
Get Key
Description: Retrieves public key by alias name.
Since: 2.8.1
Security: Admin only
Usage: GET keys/gpg/{alias-name}
Consumes: application/json
{ "alias": "alias-name" "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----...-----END PGP PUBLIC KEY BLOCK-----", }
Get Keys List
Description: Retrieves the list of all keys.
Since: 2.8.1
Security: Admin only
Usage: GET /keys/gpg/aliases
Consumes: application/json
[{ "alias": "alias-name", "default": false|true, "passphrase": false|true }, ....... ]
Delete Key
Description: Deletes the key.
Since: 2.8.1
Note: If a default key is deleted, the oldest key uploaded will be used as the default automatically.
Security: Admin only
Usage: DELETE /keys/gpg/{alias_name}
Request headers: N/A
Consumes: application/json
Propagate GPG Signing Keys to a Distribution Edge
Description: Propagate the GPG key pair to a newly added Distribution Edge.
Since: 2.4
Notes: Requires Mission Control version 4.5.0 and above.
Security: Admin only
Usage: POST /api/v1/keys/{protocol: pgp|gpg}/propagate
Request headers: N/A
Consumes: application/json
From Distribution release 2.13.2, GPG keys are propagated as follows:
Propagation Behavior | Explanation |
---|---|
When no parameters are provided | The default key will be propagated. |
When api/v1/keys/pgp/propagate?all=true | Propagates all available keys. |
When api/v1/keys/pgp/propagate?alias =<alias name> | Propagates the key with the alias name. For example, Propagation is possible by either alias key or all keys but not both. |
response: { "report": { "message" : "error message if exists" "status" : PARTIAL_SUCCESS | SUCCESS | FAILURE | PROPAGATION_NOT_REQUESTED | PROPAGATION_NOT_SUPPORTED_BY_MISSION_CONTROL | NO_GPG_KEY_TO_PROPAGATE "details" : [ { "jpd_id" : "id1", "name" : "US-EAST" "key_alias" : "my first key" "status" : "SUCCESS" }, { "jpd_id" : "id2", "name" : "US-WEST" "key_alias" : "my first key" "status" : "SUCCESS" }, ] } }
Upload GPG Signing Key for Distribution
Description: Upload GPG keys pair to JFrog Distribution. This keys pair will be used to sign Release Bundles.
Since: 1.0
$ curl -u user:password -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/keys/gpg" -T gpg.json
{ "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK----- .... -----END PGP PUBLIC KEY BLOCK-----", "private_key": "-----BEGIN PGP PRIVATE KEY BLOCK----- .... -----END PGP PRIVATE KEY BLOCK-----" }
Response status codes:
200 - Keys were successfully set.
{ "status_code”: 201, "message": "Set GPG public & private key" }
Get Public Key
Description: Returns the public GPG key set in Distribution.
Note: The private key field will be displayed in the JSON response format, only if the private key exists in the DB for that public key.
When GPG public key was not uploaded in the first place, the following message is returned: "No public GPG key exists in Distribution".
Since: 2.3.0
Security: Authenticated users only. Users must have read permissions for the Release Bundle.
Usage: GET /api/v1/keys/gpg
Consumes: application/json
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/keys/gpg"
Response:
{ "public_key": "<public gpg key>", "private_key": "****" }
RELEASE BUNDLES
Create Release Bundle Version
Description: Create a new release bundle version.
$ curl -u user:password -H "Accept: application/json" -H "Content-Type: application/json" -H "X-GPG-PASSPHRASE: keysPassphrase" -X POST "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle" -T createbundle.json
{ "name": "", "version": "", "dry_run": true|false, "sign_immediately": true|false, "storing_repository": "repository-name"|null, "description": "", "release_notes": { "syntax": "markdown|asciidoc|plain_text", "content": "" }, "spec": { "queries": [ { "aql": "items.find({ \"repo\" : \"example-repo-local\" })", "query_name": "query-1" "mappings": [ { "input": "regex", "output": "$1/$2" } ], "added_props": [ { "key": "", "values": [""] } ], "exclude_props_patterns": [ "example_exclude_prop_pattern_1", "example_example_prop_pattern_2" ] } ] } }
Field | Type | Required | Default Value | Since | Description |
---|---|---|---|---|---|
name | String | yes | N/A | 1.0 | Release bundle name |
version | String | yes | N/A | 1.0 | Release bundle version |
dry_run | Boolean | no | false | 1.0 | If true, only parses and validates. Note: this parameter default was previously set to true in versions below 2.x. |
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). |
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 | deprecated | N/A | 2.0 | |
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 Note that the release bundle query name length must be between 2 and 32 characters long and must start with alphabetic character followed by an alphanumeric or '_-.:' characters only. |
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 on the distributed artifacts. |
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". |
spec.exclude_props_patterns | List (String) | no | null | 2.5.0 | List of patterns for Properties keys to exclude after distribution of the release bundle. This will not an effect on the "added_props " properties. |
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
{ "name": "bundle-name", "version": "1.0", "state": "OPEN", "created": "2018-03-14T10:19:30.678Z", "artifacts": [ { "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:
builds.find({"name":"buileName", "number":"buildNumber"}).include("module.artifact.item")
builds.find({"name":"buildName", "number":"buildNumber"}).include("module.dependency.item")
Dynamic Release Bundle
Description: Creates, signs, and distributes an ad-hoc Release Bundle to Distribution Edges.
Since: 2.8.1
Security: Authenticated users only. User must have matching Release Bundle write permissions.
Usage: POST api/v1/dynamic/distribute
{ "storing_repository": "repo-name" "spec": { "queries": [ { "aql": "items.find({\"$and\": [{\"$or\": [{\"repo\": {\"$eq\": \"example-repo-local\"}}]}]})", "query_name": "demo-aql" } ] }, "distribution_rules": [ { "site_name": "?wildcard*", "city_name": "?wildcard*", "country_codes": ["?wildcard*"] } ] }
Update Release Bundle Version
Description: Updates an existing unsigned release bundle version.
$ curl -u user:password -H "Accept: application/json" -H "Content-Type: application/json" -H "X-GPG-PASSPHRASE: keysPassphrase" -X PUT "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/:version" -T createbundle.json
{ "dry_run": true|false, "sign_immediately": true|false, "description": "", "storing_repository": "repository-name"|null, "release_notes": { "syntax": "markdown|asciidoc|plain_text", "content": "" }, "spec": { "queries": [ { "aql": "items.find({ \"repo\" : \"example-repo-local\" })", "query_name": "query-1" "mappings": [ { "input": "regex", "output": "$1/$2" } ], "added_props": [ { "key": "", "values": [""] } ], "exclude_props_patterns": [ "example_exclude_prop_pattern_1", "example_example_prop_pattern_2" ] } ] } }
Field | Type | Required | Default Value | Since | Description |
---|---|---|---|---|---|
dry_run | Boolean | no | false | 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). |
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.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 Note that the release bundle query name length must be between 2 and 32 characters long and must start with alphabetic character followed by an alphanumeric or '_-.:' characters only. |
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 on distributed artifacts |
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". |
spec.exclude_props_patterns | List (String) | no | null | 2.5.0 | List of patterns for Properties keys to exclude after distribution of the release bundle. This will not an effect on the " |
Response status codes:
200 - Successfully updated release bundle version
400 - Release bundle version is signed
X - Status code for error passed from Artifactory AQL
{ "name": "bundle-name", "version": "1.0", "state": "OPEN", "created": "2018-03-14T10:19:30.678Z", "artifacts": [ { "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:
builds.find({"name":"buileName", "number":"buildNumber"}).include("module.artifact.item")
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
$ curl -u user:password -H "Accept: application/json" -H "Content-Type: application/json" -H "X-GPG-PASSPHRASE: keysPassphrase" -X POST "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/:version/sign"
Field | Type | Required | Default Value | Since | Description |
---|---|---|---|---|---|
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). |
signing_key_alias | String | no | Default key | 2.8.1 | The name of the key that will be used to sign the Release Bundle. If no alias is provided, the default key will be used. |
Response status codes:
200 - Successfully signed release bundle version
400 - Release bundle version is already signed
Response headers: N/A
Produces: application/json
{ "name": "bundle-name", "version": "1.0", "state": "SIGNED", "created": "2018-03-14T10:19:30.678Z", "artifacts": [ { "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 Versions of all Release Bundles
Description: Returns all the release bundle versions. This endpoint supports pagination, returning up to 10 release bundles per page.
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle?start_pos=0"
Response status codes:
200 - Success
X-RangeLimit-Total - number
Produces: application/json
[ { "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", "created_by":"[username]", "distributed_by":"[username]" "artifacts": [], "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.
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name?start_pos=0"
Response status codes:
X-RangeLimit-Total - number
Produces: application/json
[ { "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", "created_by":"[username]", "distributed_by":"[username]", "artifacts": [ { "checksum": "5880e05b5886a2fcd9a5a6dace38cd4f243affa06719c5e63116b16094e95a31", "props": [ { "key": "build.timestamp", "values": ["1521049005953"] }, ... ], "source_repo_path": "artifactory-generic/artifactory-client-java-api-0.9.2.jar", "target_repo_path": "artifactory-generic/artifactory-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.
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/:version?format=json"
Response status codes:
Produces: application/json (default)
{ "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", "created_by":"[username]", "distributed_by":"[username]", "artifacts": [ { "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 }
{ "header": "eyJraWQiOiIzZWFiNGEiLCJhbGciOiJSUzI1NiJ9", "payload": "eyJuYW1lIjoiYnVuZGxlLW5hbWUiLCJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXNjcmlwdGlvbiI6IkJ1bmRsZSBkZXNjcmlwdGlvbiIsInJlbGVhc2Vfbm90ZXMiOnsiY29udGVudCI6InJlbGVhc2Ugbm90ZXMgZGVzY3JpcHRpb24gdGV4dCIsInN5bnRheCI6InBsYWluX3RleHQifSwiY3JlYXRlZCI6IjIwMTgtMDUtMDJUMDg6NDU6MTYuODYwWiIsImFydGlmYWN0cyI6W3sicmVwb19wYXRoIjoiZXhhbXBsZS1yZXBvLWxvY2FsL2FjaGFuZ2UvU2NyZWVuIFNob3QgMjAxOC0wNC0wNSBhdCAxMC40Ny4xNi5wbmciLCJjaGVja3N1bSI6IjVhNzMwYjAxZTgxZTJhYTNiNTE4OGJjZWYzYmU4ZTRlN2Q2MWY4M2I2MTU2YjIyYTMzYzlhM2YyM2ZmMzhlMTkiLCJwcm9wcyI6W3sia2V5IjoiamlyYSIsInZhbHVlcyI6WyIxIl19XX0seyJyZXBvX3BhdGgiOiJleGFtcGxlLXJlcG8tbG9jYWwvYWNoYW5nZS9TY3JlZW4gU2hvdCAyMDE4LTA0LTA1IGF0IDEwLjQ3LjE2ICgyKS5wbmciLCJjaGVja3N1bSI6IjIzMzY2Mzk5N2EyZGYxY2FmZDZhZWI1NjkxNjZhZjkxZjYzZDQwZjRmNDFiNjgxY2JlN2RmMjlkMWE1YzE3MGEiLCJwcm9wcyI6W3sia2V5IjoiamlyYSIsInZhbHVlcyI6WyIxIl19XX0seyJyZXBvX3BhdGgiOiJleGFtcGxlLXJlcG8tbG9jYWwvYWNoYW5nZS9TY3JlZW4gU2hvdCAyMDE4LTA0LTA1IGF0IDEwLjQ3LjE2IDEucG5nIiwiY2hlY2tzdW0iOiI1YTczMGIwMWU4MWUyYWEzYjUxODhiY2VmM2JlOGU0ZTdkNjFmODNiNjE1NmIyMmEzM2M5YTNmMjNmZjM4ZTE5IiwicHJvcHMiOlt7ImtleSI6ImppcmEiLCJ2YWx1ZXMiOlsiMSJdfV19LHsicmVwb19wYXRoIjoiZXhhbXBsZS1yZXBvLWxvY2FsL2FjaGFuZ2UvU2NyZWVuIFNob3QgMjAxOC0wNC0wNSBhdCAxMC40Ny4xNiAoMykucG5nIiwiY2hlY2tzdW0iOiJjYmZjZjk0NzkzYzQ1ZTk5NmY2YTQxODY5M2ZjYjBhZDU1NzRkMzJiYzUwN2NjNmVjMDAzMDkxMmFjMWQ3MDUzIiwicHJvcHMiOlt7ImtleSI6ImppcmEiLCJ2YWx1ZXMiOlsiMSJdfV19XX0", "signature": "QWzTD2uXhLw5FW1483qEYA_h47jak8YE24mLwuF1UcT9yTYZBdEMrFWTz0uZVrPtlqi65Ek6oNeSFZO657sjpuTOpfPIg053nxOoIa4mxlxMS5nCM50Xj3qobcll0P_sX8Il8AGWbX9oI9HvSGAKYbxmu-3kVs0W1tCacb_VuHsL5KkgY2Thq5dBKhQ73aS1cE-CnFobQKGcsx10eFhEFV8VbajGLpKV8nhERDE4XA5oRARA-CczLlEYNnvn5aRD-Q1n5yI7Cys8hoDIxDLT2OCQ5alb9h4D4w7mGJrtQG0xNWsstGOTSL1HLXAe27qvBxCIsp6afX675AkOs1Eg0g" }
eyJraWQiOiIzZWFiNGEiLCJhbGciOiJSUzI1NiJ9.eyJuYW1lIjoiYnVuZGxlLW5hbWUiLCJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXNjcmlwdGlvbiI6IkJ1bmRsZSBkZXNjcmlwdGlvbiIsInJlbGVhc2Vfbm90ZXMiOnsiY29udGVudCI6InJlbGVhc2Ugbm90ZXMgZGVzY3JpcHRpb24gdGV4dCIsInN5bnRheCI6InBsYWluX3RleHQifSwiY3JlYXRlZCI6IjIwMTgtMDUtMDJUMDg6NDU6MTYuODYwWiIsImFydGlmYWN0cyI6W3sicmVwb19wYXRoIjoiZXhhbXBsZS1yZXBvLWxvY2FsL2FjaGFuZ2UvU2NyZWVuIFNob3QgMjAxOC0wNC0wNSBhdCAxMC40Ny4xNi5wbmciLCJjaGVja3N1bSI6IjVhNzMwYjAxZTgxZTJhYTNiNTE4OGJjZWYzYmU4ZTRlN2Q2MWY4M2I2MTU2YjIyYTMzYzlhM2YyM2ZmMzhlMTkiLCJwcm9wcyI6W3sia2V5IjoiamlyYSIsInZhbHVlcyI6WyIxIl19XX0seyJyZXBvX3BhdGgiOiJleGFtcGxlLXJlcG8tbG9jYWwvYWNoYW5nZS9TY3JlZW4gU2hvdCAyMDE4LTA0LTA1IGF0IDEwLjQ3LjE2ICgyKS5wbmciLCJjaGVja3N1bSI6IjIzMzY2Mzk5N2EyZGYxY2FmZDZhZWI1NjkxNjZhZjkxZjYzZDQwZjRmNDFiNjgxY2JlN2RmMjlkMWE1YzE3MGEiLCJwcm9wcyI6W3sia2V5IjoiamlyYSIsInZhbHVlcyI6WyIxIl19XX0seyJyZXBvX3BhdGgiOiJleGFtcGxlLXJlcG8tbG9jYWwvYWNoYW5nZS9TY3JlZW4gU2hvdCAyMDE4LTA0LTA1IGF0IDEwLjQ3LjE2IDEucG5nIiwiY2hlY2tzdW0iOiI1YTczMGIwMWU4MWUyYWEzYjUxODhiY2VmM2JlOGU0ZTdkNjFmODNiNjE1NmIyMmEzM2M5YTNmMjNmZjM4ZTE5IiwicHJvcHMiOlt7ImtleSI6ImppcmEiLCJ2YWx1ZXMiOlsiMSJdfV19LHsicmVwb19wYXRoIjoiZXhhbXBsZS1yZXBvLWxvY2FsL2FjaGFuZ2UvU2NyZWVuIFNob3QgMjAxOC0wNC0wNSBhdCAxMC40Ny4xNiAoMykucG5nIiwiY2hlY2tzdW0iOiJjYmZjZjk0NzkzYzQ1ZTk5NmY2YTQxODY5M2ZjYjBhZDU1NzRkMzJiYzUwN2NjNmVjMDAzMDkxMmFjMWQ3MDUzIiwicHJvcHMiOlt7ImtleSI6ImppcmEiLCJ2YWx1ZXMiOlsiMSJdfV19XX0.QWzTD2uXhLw5FW1483qEYA_h47jak8YE24mLwuF1UcT9yTYZBdEMrFWTz0uZVrPtlqi65Ek6oNeSFZO657sjpuTOpfPIg053nxOoIa4mxlxMS5nCM50Xj3qobcll0P_sX8Il8AGWbX9oI9HvSGAKYbxmu-3kVs0W1tCacb_VuHsL5KkgY2Thq5dBKhQ73aS1cE-CnFobQKGcsx10eFhEFV8VbajGLpKV8nhERDE4XA5oRARA-CczLlEYNnvn5aRD-Q1n5yI7Cys8hoDIxDLT2OCQ5alb9h4D4w7mGJrtQG0xNWsstGOTSL1HLXAe27qvBxCIsp6afX675AkOs1Eg0g
Get Last Release Bundle Version
Description: Retrieves the latest version of a Release Bundle.
Note: Latest is a reserved word. Release Bundle versions cannot contain this word.
Since: 2.3.0
Security: Authenticated users only. Users must have read permissions for the Release Bundle.
Usage: /api/v1/release_bundle/:name/:LATEST
Request headers: N/A
Consumes: N/A
cURL
$ curl -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/LATEST"
Response status codes:
200 - Success
403 - No permission for the Release Bundle
404 - Release Bundle or Release Bundle version not found
Response
{ "name": "the_release_bundle", "version": "6", "storing_repository": "release-bundles", "description": "Maven bundle description", "created": "2020-05-03T12:33:40.759+0300", "created_by": "[username]", "distributed_by": "[username]", "artifacts": [ { "checksum": "d4f8baa9d0b46aa1e5d9e60bfd7acc1265c51723844d81ad0b2dfc9f702e89f8", "props": [], "sourceRepoPath": "release-bundles/the_release_bundle/6/example-repo-local/folder1/public_key.txt", "targetRepoPath": "example-repo-local/folder1/public_key.txt" }, { "checksum": "c7e875ebb4a69de287eb040375a88d254acf85c2b69dc9a59689d657e7f2d3cb", "props": [], "sourceRepoPath": "release-bundles/the_release_bundle/6/example-repo-local/audio-1.5.0.tar.gz", "targetRepoPath": "example-repo-local/audio-1.5.0.tar.gz" } ], "artifacts_size": 2892, "archived": false, "state": "SIGNED", "spec": { "queries": [ { "aql": "items.find({ \"repo\" : \"example-repo-local\" })", "query_name": "query-0", "mappings": [], "added_props": [], "query_type": "AQL" } ], "exclude_props_patterns": [ "example_exclude_prop_pattern_1", "example_example_prop_pattern_2" ] } }
Delete Release Bundle All Versions
Description: Deletes all versions of a release bundle on JFrog Distribution only. To delete from the Distribution Edge where it was distributed, see Delete Release Bundle Version from Distribution Edges.
$ curl -u user:password -X DELETE "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name"
Response status codes:
204 - Successfully deleted release bundle versions
404 - Release bundle not found
Produces: N/A
Delete Release Bundle Version
Description: Deletes specific release bundle version on JFrog Distribution only.
$ curl -u user:password -X DELETE "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/:version"
Response status codes:
204 - Successfully deleted release bundle version
404 - Release bundle or release bundle version not found
Export Release Bundle Version Archived File
Description: Triggers the Release Bundle export process from JFrog Distribution. For more information, see Distributing Release Bundles in an Air Gap Environment.
Note: The Import process is performed on the Distribution Edge.
Since: 2.5
Security: Authenticated users only. Users must have matching Release Bundle distribute permissions.
Usage: POST api/v1/export/release_bundle/{name}/{version}
curl -XPOST 'http://localhost:8082/distribution/api/v1/export/release_bundle/{name}/{version}' -uadmin:password
Field | Type | Required | Default Value | Since | Description |
---|---|---|---|---|---|
name | String | yes | N/A | 2.5 | Release bundle name |
version | String | yes | N/A | 2.5 | Release bundle version |
Response status codes:
202 - Successfully triggered the process of generating an archived Export version
400 - Failed to generate an export version archive file
Get Exported Release Bundle Version Status
Description: Gets the status of an exported Release Bundle process. For more information, see Distributing Release Bundles in an Air Gap Environment.
Since: 2.5
Security: Authenticated users only. Users must have matching Release Bundle distribute permissions.
Usage: GET api/v1/export/release_bundle/{name}/{version}/status
Consumes: application/json
curl -XGET 'http://localhost:8082/distribution/api/v1/export/release_bundle/{name}/{version}/status' -uadmin:password
Response status codes:
202 - Successful request
400 - Failed to return the status
{ "status":"IN_PROGRESS|FAILED|NOT_TRIGGERED|COMPLETED", "message":"optional message in case failed and we have some info to pass", "download_url":"http://artifactory_url/path_if_status_completed" }
Delete Exported Release Bundle Archive File
Description: Deletes the exported Release Bundle archive from Distribution. For more information, see Distributing Release Bundles in an Air Gap Environment.
Since: 2.5
Security: Authenticated users only. Users must have delete permissions for the Release Bundle.
Usage: DELETE api/v1/export/release_bundle/{name}/{version}
Consumes: N/A
curl -X DELETE 'http://localhost:8082/distribution/api/v1/export/release_bundle/{name}/{version}
DISTRIBUTION
Distribute Release Bundle Version
Description: Schedules a release bundle version for distribution to Distribution Edges. Action tracking ID will be returned.
Since: 1.0
Security: Authenticated users only. User must have distribution permission for the release bundle. The Distribution Edges will be filtered by the user's permissions.
Change in Permissions from Release 2.13.2
From Distribution 2.13.2, the user must have:
- Read and deploy permissions on the target repositories
- Permissions on the destination repository
- Distribution permissions on the required Release Bundle
This is a breaking change from previous versions, whereby any user with any permissions could distribute release bundles.
Usage: POST /api/v1/distribution/:name/:version
Request headers: N/A
Consumes: application/json
$ curl -u user:password -H "Content-Type: application/json" -X POST "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/distribution/:name/:version" -T distribute.json
{ "dry_run": true|false, "auto_create_missing_repositories": true|false, "distribution_rules": [ { "site_name": "?wildcard*", "city_name": "?wildcard*", "country_codes": ["?wildcard*"] } ] }
Field | Type | Required | Default Value | Description |
---|---|---|---|---|
| Boolean | no | false | If true, only parses and validates. |
| Boolean | no | false | From version 2.8.1. If true, this enables you to automatically create missing target repositories on the target edges or Artifactory when distributing Release Bundles. For more information, see Target Repository Auto-Creation. |
| List (Object) | yes | N/A | Describes the filters by which Distribution Edge are selected. Must resolve at least one edge. |
| String | no | "*" | Wildcard filter for site name |
| String | no | "*" | Wildcard filter for site city name |
| List (String) | no | [ "*" ] | Wildcard filters for site country codes |
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
{ "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 Distribution Edges.
Usage: PUT /api/v1/distribution/:name/:version/abort
$ curl -u user:password -X PUT "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/distribution/:name/:version/abort"
Response status codes:
202 - Successfully scheduled distribution interruption. Returns the list of Distribution Edges affected by the stop request.
204 - No Distribution Edge with distribution in progress found
404 - Release bundle or release bundle version not found
Produces: application/json
[ { "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 Distribution Edges
Description: Schedules a release bundle version for deletion in Distribution Edges. Action tracking ID will be returned. Have a parameter to keep or delete release bundle from JFrog Distribution on success.
Usage: POST /api/v1/distribution/:name/:version/delete
$ curl -u user:password -H "Content-Type: application/json" -X POST "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/distribution/bundle98/version100/delete" -T delete.json
{ "dry_run": true|false, "distribution_rules": [ { "site_name": "?wildcard*", "city_name": "?wildcard*", "country_codes": ["?wildcard*"] } ], "on_success": "keep|delete" }
Field | Type | Required | Default Value | Description |
---|---|---|---|---|
dry_run | Boolean | no | true | If true, only parses and validates |
distribution_rules | List (Object) | yes | N/A | Describes the filters by which Distribution Edges are selected. Must resolve at least one edge. |
distribution_rules.site_name | String | no | "*" | Wildcard filter for site name |
distribution_rules.city_name | String | no | "*" | Wildcard filter for site city name |
distribution_rules.country_codes | List (String) | no | [ "*" ] | Wildcard filters for site country codes |
on_success | String | no | keep | Action to be performed on the release bundle version in JFrog Distrubution itself after deletion is complete in the specified Distribution Edge/s. |
Response status codes:
200 - Success for dry_run
202 - Successfully scheduled deletion
404 - Release bundle or release bundle version not found
Produces: application/json
{ "id": 188527534551203840, "sites": [ { "service_id": "jfrt@01cc8hkzy1zgtc1wqw3zk41p2a", "name": "US_NY_Art01", "type": "edge" }, ... ] }
Get Distribution Status Details
Description: Get status details for all distributions.
Consumes: N/A
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/distribution"
Response status codes:
200 - Success
Produces: application/json
[ { "distribution_id": 188527534551203840, "distribution_friendly_id": 1, "created_by":"[username]", "distributed_by":"[username]", "start_time":"[YYY-MM_DDTHH:HH:MM:SS.MI:Sec+UTF]", "finish_time":[YYY-MM_DDTHH:HH:MM:SS.MI:Sec+UTF],"duration":[milliseconds], "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": ["*"] }, ... ], "sites": [ { "status": "Not distributed | In progress | Completed | Failed", "general_error": "<error explanation>", "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.
Consumes: N/A
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/distribution"
Response status codes:
200 - Success
Produces: application/json
[ { "distribution_id": 188527534551203840, "distribution_friendly_id": 1, "created_by":"[username]", "distributed_by":"[username]", "start_time":"[YYY-MM_DDTHH:HH:MM:SS.MI:Sec+UTF]", "finish_time":[YYY-MM_DDTHH:HH:MM:SS.MI:Sec+UTF], "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": ["*"] }, ... ], "sites": [ { "status": "Not distributed | In progress | Completed | Failed", "general_error": "<error explanation>", "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.
Consumes: N/A
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/:version/distribution"
Response status codes:
200 - Success
Produces: application/json
[ { "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": ["*"] }, ... ], "sites": [ { "status": "Not distributed | In progress | Completed | Failed", "general_error": "<error explanation>", "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.
Consumes: N/A
$ curl -X GET -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/:version/distribution/:tracker_id"
Response status codes:
200 - Success
Produces: application/json
{ "distribution_id": 188527534551203840, "distribution_friendly_id": 1, "created_by":"[username]", "distributed_by":"[username]", "start_time":"[YYY-MM_DDTHH:HH:MM:SS.MI:Sec+UTF]", "finish_time":[YYY-MM_DDTHH:HH:MM:SS.MI:Sec+UTF], "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": ["*"] }, ... ], "sites": [ { "status": "Not distributed | In progress | Completed | Failed", "general_error": "<error explanation>", "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.
$ curl -X POST -u user:password http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/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
Produces: application/json
{ "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" }
Field | Type | Required | Default Value | Description |
---|---|---|---|---|
grant_type | String | no | client_credentials | The 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. |
username | String | yes | 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. | |
scope | String | no | 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_in | Long | no | 0 | The time in seconds for which the token will be valid. To specify a token that never expires, set to zero. |
refreshable | Boolean | no | false | If true, this token is refreshable and the refresh token can be used to replace it with a new token once it expires. |
Refresh a Token
Since: 1.2
Field | Type | Required | Default Value | Description |
---|---|---|---|---|
grant_type | String | yes | The grant type used to authenticate the request. In this case, the only value supported is "refresh_token". | |
access_token | String | yes | The access token to refresh. | |
refresh_token | String | yes | The refresh token of the access token that needs to be refreshed. | |
expires_in | Long | no | 0 | The time in seconds for which the token will be valid. To specify a token that never expires, set to zero. |
refreshable | Boolean | no | true | If true, this token is refreshable and the refresh token can be used to replace it with a new token once it expires. |
$ curl -X POST -u user:password http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/security/token -d "grant_type=refresh_token" -d "refresh_token=fgsg53t3g…" -d "access_token=gsfdgw35gt..."
Response status codes:
200 - Successfully refreshed token
Produces: application/json
{ "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
$ curl -u user:password -X POST "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/security/token/revoke" -d "token=fasdt3..."
or
$ curl -u user:password -X POST "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/security/token/revoke" -d "token_id=7e0eec..."
Field | Type | Required | Description |
---|---|---|---|
token | String | yes (if token_id is empty) | The token to be revoked. Must not be specified if token_id specified. |
token_id | String | yes (if token is empty) | The ID of the token to be revoked. Must not be specified if token specified. |
Response status codes:
Get Tokens Info
Description: Gets a list of access tokens for a specific user.
$ curl -u user:password -X GET "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/security/token"
Response status codes:
Produces: application/json
{ "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
Permission action types:
d | delete |
x | distribute |
Create/Update Destinations Permissions by Name
Permissions can be created and overridden by specifying the unique permission name.
Destination permission is used to define permissions for interactions with Distribution Edges, such as distributing and deleting release bundles.
Allowed actions for destination permission: x, d.
The permissions are applied to Distribution Edges which information is matched by the passed wildcard expressions.
Description: Create/Update permissions for users and groups, based on permission scope. The response body will contain the created/updated permission.
$ curl -X PUT -u user:password -H "Content-Type: application/json" "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/security/permissions/:name" -T permission.json
{ "distribution_destinations": [ { "site_name": "*", "city_name": "*", "country_codes": [ "*" ] } ], "name": "permission-name", "resource_type": "destination", "principals": { "users": { "anonymous": [ "x" ] }, "groups": { "readers": [ "x" ] } } }
200 - Successfully set permission
Response headers: N/A
{ "distribution_destinations": [ { "site_name": "*", "city_name": "*", "country_codes": [ "*" ] } ], "name": "permission-name", "resource_type": "destination", "principals": { "users": { "user1": [ "x" ] }, "groups": { "group1": [ "x" ] } } }
Get All Permissions
Description: Get all permissions.
Usage: GET /api/v1/security/permissions
Request Headers: N/A
Consumes: application/json
$ curl -X GET -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/security/permissions"
Response status codes:
200 - Success
Produces: application/json
[ { "distribution_destinations": [ { "site_name": "*", "city_name": "*", "country_codes": [ "*" ] } ], "name": "permission-name", "resource_type": "destination", "principals": { "users": { "anonymous": [ "x" ] }, "groups": { "readers": [ "x" ] } } } ]
Get Permission by name
Description: Get permission information by name.
$ curl -X GET -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/security/permissions/:name
Response status codes:
200 - Success
404 - Permission not found
Produces: application/json
{ "distribution_destinations": [ { "site_name": "*", "city_name": "*", "country_codes": [ "*" ] } ], "name": "permission-name", "resource_type": "destination", "principals": { "users": { "anonymous": [ "x" ] }, "groups": { "readers": [ "x" ] } } }
Delete Permission by name
Description: Delete permission by it's id
$ curl -X DELETE -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/security/permissions/:name"
Response status codes:
204 - Successfully deleted permission
404 - Permission not found
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
$ curl -X POST -u user:password -H "Content-Type: application/json" "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/support/bundle" -T 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": "" }
Field | Type | Required | Default Value | Since | Description |
---|---|---|---|---|---|
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 | String | no | Today | 1.6 | End 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 | String | no | N/A | 1.6 | Support bundle name |
Response status codes:
200 - Successfully create support bundle
Response headers: N/A
Produces: application/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
$ curl -X PUT -u user:password -H "Content-Type: application/json" "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/support/bundle/:bundle_id" -T 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": "" }
Field | Type | Required | Default Value | Since | Description |
---|---|---|---|---|---|
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 | String | no | Today | 1.6 | End 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 | String | no | N/A | 1.6 | Support bundle name |
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 Edge.
404 - Artifactory authentication provider could not be found
Response headers: N/A
Produces: application/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
$ curl -X GET -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/support/bundle/:bundle_id"
Response status codes:
200 - Successfully get support bundle info
404 - Support bundle not found
Response headers: N/A
Produces: application/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, }
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
$ curl -X GET -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/support/bundle/:bundle_id/archive" --output support_bundle.zip
Response status codes:
200 - Successfully download support bundle
404 - Support bundle not found
Response headers: N/A
200 OK Content-Type: application/zip
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
$ curl -X DELETE -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/support/bundle/:bundle_id"
Response status codes:
204 - Successfully delete support bundle
404 - Support bundle not found
Response headers: N/A
204 No Content
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
$ curl -X GET -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/support/bundles"
Response status codes:
200 - Success
Response headers: N/A
{ "count": 2, "bundles": [ { id: 20181230145474-53666747, description: "", name: "", created: 2018-12-30, }, …. ] }
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
$ curl -XGET -u admin:password "http://localhost:8080/api/v1/maintenance/generate_token/stop_all"
{ "token":"JEv4CnrZNhmgtkRV9aKmGsrozGEoaoBs3okv9SFusdhR3hUKiWdKwAhoeP1SLEy8hFZqFhE" }
Response status codes:
200 - Success
Stop All Tasks
Description: Stops all running distribution tasks. Requires an execution token.
Since: 1.8.1
Security: Admin only
Usage: POST /api/v1/maintenance/execute/stop_all
Request headers: N/A
Consumes: Content-Type: text/plain
Produces: application/json
$ curl -XPOST -H "Content-Type: text/plain" -u admin:password "http://localhost:8080/api/v1/maintenance/execute/stop_all?dryRun=false" --data-raw "token..."
Field | Type | Required | Default Value | Since | Description |
---|---|---|---|---|---|
dryRun | Query Param | yes | true | 1.8.1 | If true, only parses and validates. |
{ "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
XRAY
Triggers Xray Release Bundle Version Indexing
Description: Triggers Xray indexing of the release bundle version.
Since: 2.0.0
Security: Authenticated users only. User must have matching Release Bundle write permissions.
Usage: POST /api/v1/release_bundle/:name/:version/trigger_xray_scan
Request headers: N/A
Consumes: N/A
$ curl -X POST -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/release_bundle/:name/:version/trigger_xray_scan
Response status codes:
200 - Success
IMPORT & EXPORT
Get Source Artifactory IDs
Description: Lists the Artifactory IDs containing Release Bundles. Used as the preliminary step, prior to exporting the Release Bundles metadata to the relevant Distribution services.
Notes: To support the One to One Pairing ratio between Artifactory (from 7.x) and Distribution (from 2.4) introduced in the JFrog Platform, you need to migrate the Distribution metadata to Distribution services based on the list generated by this command. For more information, see Distribution REST API.
Since: 2.4
Security: Requires an admin user
Usage: GET /api/v1/system/migration/import_export/source_artifactories
Consumes: application/json
Produces: application/json
Sample Usage:
$ curl -X GET -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/migration/import_export/source_artifactories
Export Distribution Release Bundle Metadata
Description: Exports the Release Bundles metadata on the Distribution service to an export.zip
file.
Notes: To support the Artifactory to Distribution one to one paring ratio introduced in the JFrog Platform, you need to migrate the Distribution Release Bundle metadata to its relevant Distribution service according to the <Artifactory_instance_ID> associated with its correlating Distribution service.
Since: 2.4
Security: Requires an admin user
Usage: POST /api/v1/system/migration/export/<Artifactory_instance_ID> -o export.zip
Produces: application/zip
Sample Usage:
$ curl -X POST -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/migration/export/DEV_Art01 -o export.zip
Sample Response:
Please provide an example
Import Distribution Release Bundle Metadata
Description: Imports the Release Bundles to the newly created Distribution service from the exported zip file. For more information, see Distribution REST API.
Notes: To support the One to One Pairing between Artifactory (from 7.x) and Distribution (from 2.4), run this command to import the Release Bundle Metadata from the core Distribution service to the newly created Distribution service. For more information, see Distribution REST API.
Since: 2.4
Security: Requires an admin user
Usage: POST /api/v1/system/migration/import
Consumes: multipart/form-data
Sample Usage:
$ curl -X POST -u user:password "http://ARTIFACTORY_SERVER_HOSTNAME:8082/distribution/api/v1/system/migration/import
ERROR RESPONSES
Status code | Reason | Suggested actions |
---|---|---|
400 | Invalid request parameters (headers / body) | Compare request against specification |
401 | Endpoint requires authentication | Repeat request with authentication credentials |
403 | Endpoint permission requirements are not met | Response will include necessary permissions |
500 | Unexpected error during request handling | Check distribution logs |