Usage

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

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

Authentication

JFrog Container Registry's REST API supports these forms of authentication:

  • Basic authentication using your username and password
  • Basic authentication using your username and API Key.

  • Using a dedicated header (X-JFrog-Art-Api) with your API Key.
  • Using an access token instead of a password for basic authentication.
  • Using an access token as a bearer token in an authorization header (Authorization: Bearer) with your access token.

Using JFrog CLI

JFrog CLI is a compact and smart client that provides a simple interface to automate access to JFrog Container Registry. As a wrapper to the REST API, it offers a way to simplify automation scripts making them more readable and easier to maintain, features such as parallel uploads and downloads, checksum optimization and wildcards/regular expressions make your scripts more efficient and reliable. Please note that several of the functions available through the REST API are also available through JFrog CLI and you should consider which method best meets your needs.

For more details on download, installation and usage of JFrog CLI, please refer to the .

Example - Deploying/Downloading an Artifact

The example below demonstrates how to invoke the Deploy Artifact REST API.

  • You are using cURL from the unix command line, and are presently working from the home (~) directory of the user 'myUser'
  • You wish to deploy the file 'myNewFile.txt', which is located in your Desktop directory, ('~/Desktop/myNewFile.txt')
  • You have JFrog Container Registry running on your local system, on port 8081
  • You wish to deploy the artifact into the 'my-repository' repository, under the 'my/new/artifact/directory/' folder structure, and wish to store the file there as 'file.txt'
  • You have configured a user in JFrog Container Registry named 'myUser', with password 'myP455w0rd!', and this user has permissions to deploy artifacts
  • Your API Key is 'ABcdEF'
  • Where possible, the same example is demonstrated using JFrog CLI

To deploy the file using your username and password for authentication, you would use the following command:

curl -u myUser:myP455w0rd! -X PUT "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt
jfrog rt u file.txt my-repository/my/new/artifact/directory/ --user=myUser --password=myP455w0rd!

To download the file using your username and password for authentication, you would use the following command:

curl -u myUser:myP455w0rd! "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt"
jfrog rt dl my-repository/my/new/artifact/directory/file.txt --user=myUser --password=myP455w0rd!


To deploy the file using your API Key for basic authentication, you would use the following command:

curl -u myUser:ABcdEF -X PUT "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt
jfrog rt u file.txt my-repository/my/new/artifact/directory/ --apiKey=ABcdEF

To donwload the file using your API Key for basic authentication, you would use the following command:

curl -u myUser:ABcdEF "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt"
jfrog rt dl my-repository/my/new/artifact/directory/file.txt --apiKey=ABcdEF


To deploy the file using your API Key in a header, you would use the following command:

curl -H "X-JFrog-Art-Api:ABcdEF" -X PUT "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt


To deploy the file using your access token for basic authentication, you would use the following command:

curl -u myUser:<Token> -X PUT "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt


To deploy the file using your access token in a header, you would use the following command:

curl -H "Authorization: Bearer <Token>" -X PUT "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt

Working with JFrog Container Registry Cloud

JFrog Container Registry Cloud offers the same extensive functionality and capabilities for automation as an on-prem installation, including authentication, use of JFrog CLI and the REST API endpoints.

As a Cloud service, the URL is different from an on-prem installation and the REST API endpoints can be reached at:

https://<Server Name>.jfrog.io/<Server Name>

Example

The snippets below apply the same example described above to an JFrog Container Registry Cloud instance named "myjcrsaas" (instead of to an on-prem installation).

To deploy the file using your username and password for authentication, you would use the following command: 

curl -u myUser:myP455w0rd! -X PUT "https://myjcrsaas.jfrog.io/myjcrsaas/helm-local/server-1.0.0.tgz" -T server-1.0.0.tgz
jfrog rt u file.txt my-repository/my/new/artifact/directory/ --user=myUser --password=myP455w0rd!

Note that using JFrog CLI is identical with an JFrog Container Registry Cloud instance. You only need to configure JFrog CLI with the correct URL for your instance. 

REST Resources

The sections below provide a comprehensive listing of the REST resources exposed by JFrog Container Registry.

For details on handling errors please refer to ERROR RESPONSES below.

Usage of REST resources is subject to security restrictions applicable to each individual resource.

 

BUILDS

All Builds

Description: Provides information on all builds
Security: Requires a privileged user (can be anonymous). Requires read permission for the Build or basic read.
Usage: GET /api/build
Produces: application/json (application/vnd.org.jfrog.build.Builds+json)
Sample Output:

GET /api/build
{
    "uri": "http://localhost:8081/artifactory/api/build"
    "builds" : [
    {
        "uri" : "/my-build",
        "lastStarted" : ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
    },
    {
        "uri" : "/jackrabbit",
        "lastStarted" : ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
    }
]
}



Build Runs

Description: Build Runs
Security: Requires a privileged user (can be anonymous). Requires read permission for the build or basic read.
Usage: GET /api/build/{buildName}
Produces: application/json (application/vnd.org.jfrog.build.BuildsByName+json)
Sample Output:

GET /api/build/my-build
{
    "uri": "http://localhost:8081/artifactory/api/build/my-build"
    "buildsNumbers" : [
    {
        "uri" : "/51",
        "started" : ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
    },
    {
        "uri" : "/52",
        "started" : ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
    }
]
}

Build Upload

Description: Upload Build
Security: Requires a privileged user. Requires deploy permission for the build, and delete permission for overriding existing build info artifact.
Notes: All build modules must have the build.name and build.number properties set as well as the correct SHA1 and MD5 in order to be properly linked in the build info.
Usage: PUT /api/build/ -H "Content-Type: application/json" --upload-file build.json  
Consumes: application/json (application/vnd.org.jfrog.build.BuildsByName+json)
Example: curl -X PUT "http://localhost:8081/artifactory/api/build" -H "Content-Type: application/json" --upload-file build.json
Sample format:

{
  "properties" : {
   /* Environment variables and properties collected from the CI server.
      The "buildInfo.env." prefix is added to environment variables and build related properties.
      For system variables there's no prefix. */
   "buildInfo.env.JAVA_HOME" : "",
   ...
  },
+  "version" : "1.0.1", // Build Info schema version
+  "name" : "My-build-name", // Build name
+  "number" : "28", // Build number
-  "type" : "GENERIC", // Build type (values currently supported: MAVEN, GRADLE, ANT, IVY and GENERIC)
-  "buildAgent" : { // Build tool information
-    "name" : "GENERIC", // Build tool type
-    "version" : "1.26.1" // Build tool version
  },
- "agent" : { // CI Server information
-   "name" : "Jenkins", // CI server type
-   "version" : "1.554.2" // CI server version
   },
+  "started" : "2014-09-30T12:00:19.893+0300", // Build start time in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ
-  "artifactoryPluginVersion" : "2.3.1",
-  "durationMillis" : 9762, // Build duration in milliseconds
-  "artifactoryPrincipal" : "james", // Artifactory principal (the Artifactory user used for deployment)
-  "url" : "http://my-ci-server/jenkins/job/My-project-name/28/", // CI server URL
-  "vcsRevision" : "e4ab2e493afd369ae7bdc90d69c912e8346a3463", // VCS revision
-  "vcsUrl" : "https://github.com/github-user/my-project.git", // VCS URL
-  "buildRetention" : { // Build retention information
-  "deleteBuildArtifacts" : true, // Automatically remove build artifacts stored in Artifactory (true/false)
-   "count" : 100, // The maximum number of builds to store in Artifactory.
-   "minimumBuildDate" : 1407345768020, // Earliest build date to store in Artifactory
-   "buildNumbersNotToBeDiscarded" : [ ] // List of build numbers that should not be removed from Artifactory
  },
  /* List of build modules */   
-   "modules": [{
-       "properties": {
-           "docker.image.tag": "10.1.20.94:8080/docker-local/alpine:latest",
-           "docker.image.id": "sha256:055936d3920576da37aa9bc460d70c5f212028bda1c08c0879aedf03d7a66ea1"
        },
-       "id": "alpine:latest",
-       "artifacts": [{
-           "sha1": "38b5c4465b61e1ad87a82a7ac83334bc34d26752",
-           "sha256": "bf1684a6e3676389ec861c602e97f27b03f14178e5bc3f70dce198f9f160cce9",
-           "md5": "35e76f0617ee20d842c843f2a0164ae6",
-           "name": "manifest.json"
        }, {
-           "sha1": "4a4a284e964dc39d47de68281874e71f28cd71c9",
-           "sha256": "055936d3920576da37aa9bc460d70c5f212028bda1c08c0879aedf03d7a66ea1",
-           "md5": "6a85339254044c88a0605e717c1856a0",
-           "name": "sha256__055936d3920576da37aa9bc460d70c5f212028bda1c08c0879aedf03d7a66ea1"
        }, {
-           "sha1": "8e05dbc2b744ce6710aef60759b82b657a0c46a0",
-           "sha256": "e7c96db7181be991f19a9fb6975cdbbd73c65f4a2681348e63a141a2192a5f10",
-           "md5": "89d694074fb2763c3b2a8668af61466c",
-           "name": "sha256__e7c96db7181be991f19a9fb6975cdbbd73c65f4a2681348e63a141a2192a5f10"
        }]
    }],
  /* List of issues related to the build */
    "issues" : {
    "tracker" : {
-     "name" : "JIRA",
-     "version" : "6.0.1"
    },
-  "aggregateBuildIssues" : true,  //whether or not there are issues that already appeared in previous builds
-   "aggregationBuildStatus" : "Released",
    "affectedIssues" : [ {
-     "key" : "RTFACT-1234",
-      "url" : "https://www.jfrog.com/jira/browse/RTFACT-1234",
-      "summary" : "Description of the relevant issue",
-      "aggregated" : false  //whether or not this specific issue already appeared in previous builds
    }, {
-     "key" : "RTFACT-5469",
-     "url" : "https://www.jfrog.com/jira/browse/RTFACT-5678",
-     "summary" : "Description of the relevant issue",
-     "aggregated" : true
    } ] 
   },  
  }
}

+=mandatory; -=optional


Build Info

Description: Build Info
Security: Requires a privileged user with deploy permissions. Requires read permission for the build.
Usage: GET /api/build/{buildName}/{buildNumber}
Produces: application/json (application/vnd.org.jfrog.build.BuildInfo+json)
Sample Output:

GET /api/build/my-build/51
{
"uri": "http://localhost:8081/artifactory/api/build/my-build/51"
"buildInfo" : {
        ...
    }
}



Builds Diff

Description: Compare a build artifacts/dependencies/environment with an older build to see what has changed (new artifacts added, old dependencies deleted etc).
Security: Requires a privileged user. Requires read permission for the build.
Usage: GET /api/build/{buildName}/{buildNumber}?diff={OlderbuildNumber}
Produces: application/json (application/vnd.org.jfrog.build.BuildsDiff+json)
Sample Output:


GET /api/build/my-build/51?diff=50
{
    "artifacts": {
        "updated": [],
        "unchanged": [],
        "removed": [],
        "new": []
    }, "dependencies": {
        "updated": [],
        "unchanged": [],
        "removed": [],
        "new": []
    }, "properties": {
        "updated": [],
        "unchanged": [],
        "removed": [],
        "new": []
    }
}

Promote Docker Image

Description: Promotes a Docker image from one repository to another. Supported by local only.
Security: Requires a privileged user 
Usage: POST api/docker/<repoKey>/v2/promote
Consumes: application/json

{
    "targetRepo" : "<targetRepo>",							// The target repository for the move or copy 
    "dockerRepository" : "<dockerRepository>", 				// The docker repository name to promote
	"targetDockerRepository" : "<targetDockerRepository>"	// An optional docker repository name, if null, will use the same name as 'dockerRepository'
    "tag" : "<tag>",										// An optional tag name to promote, if null - the entire docker repository will be promoted. Available from v4.10. 
    "targetTag" : "<tag>",                     				// An optional target tag to assign the image after promotion, if null - will use the same tag
    "copy": false											// An optional value to set whether to copy instead of move. Default: false
}

Produces: application/text
Sample Usage:

POST api/docker/docker-local/v2/promote
{
  "targetRepo": "docker-prod",
  "dockerRepository": "jfrog/ubuntu"
}
POST /api/build/distribute/my-build/1
{
	"targetRepo" : "dist-repo-jfrog-artifactory",  
	"sourceRepos" : ["yum-local"]  
}

Control Build Retention

Description: Specifies retention parameters for build info

Security: Requires a privileged user. Requires delete permission for the build.
Usage: POST /api/build/retention/{buildName}?async=<true | false>
Consumes: application/json


{ 
    "deleteBuildArtifacts" : <true | false>, 	// When true, automatically removes build artifacts stored in JFrog Container Registry 
    "count" : <count>, 							// The maximum number of builds to store in JFrog Container Registry.
    "minimumBuildDate" : <date>, 				// Earliest build date to store in JFrog Container Registry - ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
    "buildNumbersNotToBeDiscarded" : [ ] 		// List of build numbers that should not be removed from JFrog Container Registry
}

Sample Usage:

POST /api/build/retention/myBuild?async=true

{ 
    "deleteBuildArtifacts" : true, 
    "count" : 100, // 
    "minimumBuildDate" : 1407345768020, 
    "buildNumbersNotToBeDiscarded" : [ 5, 9] 
}

ARTIFACTS & STORAGE

Folder Info

Description: Folder Info
For virtual use, the virtual repository returns the unified children. Supported by local, local-cached and virtual repositories.
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/storage/{repoKey}/{folder-path}
Produces: application/json (application/vnd.org.jfrog.artifactory.storage.FolderInfo+json)
Sample Output:

GET /api/storage/libs-release-local/org/acme
{
"uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme",
"repo": "libs-release-local",
"path": "/org/acme",
"created": ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"createdBy": "userY",
"lastModified": ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"modifiedBy": "userX",
"lastUpdated": ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"children": [
{
            "uri" : "/child1",
            "folder" : "true"
        },{
            "uri" : "/child2",
            "folder" : "false"
         }
]
}

File Info

Description: File Info
For virtual use the virtual repository returns the resolved file. Supported by local, local-cached and virtual repositories
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/storage/{repoKey}/{filePath}
Produces: application/json (application/vnd.org.jfrog.artifactory.storage.FileInfo+json)
Sample Output:

GET /api/storage/generic-remote/installer.zip
{
  "repo" : "generic-remote-cache",
  "path" : "/installer.zip",
  "created" : "2019-11-12T11:52:58.328+02:00",
  "createdBy" : "admin",
  "lastModified" : "2019-11-12T11:52:15.000+02:00",
  "modifiedBy" : "admin",
  "lastUpdated" : "2019-11-12T11:52:58.331+02:00",
  "downloadUri" : "http://localhost:8080/artifactory/generic-remote-cache/installer.zip",
  "remoteUrl" : "http://localhost:8081/artifactory/generic-local/installer.zip",
  "mimeType" : "application/zip",
  "size" : "53543",
  "checksums" : {
    "sha1" : "eba225b84618778988ea7d226ad039fdf2d1745f",
    "md5" : "5aa9da47c2632177247011e9b851c26a",
    "sha256" : "011d4a4af5a81bf96f3e549281e7aa831a40439632c9fea5d40b9d3711c35dcb"
  },
  "originalChecksums" : {
    "sha1" : "eba225b84618778988ea7d226ad039fdf2d1745f",
    "md5" : "5aa9da47c2632177247011e9b851c26a",
    "sha256" : "011d4a4af5a81bf96f3e549281e7aa831a40439632c9fea5d40b9d3711c35dcb"
  },
  "uri" : "http://localhost:8080/artifactory/api/storage/generic-remote-cache/installer.zip"
}

Get Storage Summary Info

Description: Returns storage summary information regarding binaries, file store and repositories
Security: Requires a privileged user (Admin only)
Usage: GET /api/storageinfo
Produces: application/json
Sample Output:


GET /api/storageinfo
{
  "binariesSummary": {
    "binariesCount""125,726",
    "binariesSize""3.48 GB",
    "artifactsSize""59.77 GB",
    "optimization""5.82%",
    "itemsCount""2,176,580",
    "artifactsCount""2,084,408"
  },
  "fileStoreSummary": {
    "storageType""filesystem",
    "storageDirectory""/home/.../artifactory-jcr/data/filestore",
    "totalSpace""204.28 GB",
    "usedSpace""32.22 GB (15.77%)",
    "freeSpace""172.06 GB (84.23%)"
  },
  "repositoriesSummaryList": [
    {
      "repoKey""docker-virtual",
      "repoType""VIRTUAL",
      "foldersCount"0,
      "filesCount"0,
      "usedSpace""0 bytes",
      "itemsCount"0,
      "packageType""Docker",
      "percentage""0%"
    },
    {
      "repoKey""repo",
      "repoType""VIRTUAL",
      "foldersCount"0,
      "filesCount"0,
      "usedSpace""0 bytes",
      "itemsCount"0,
      "packageType""Generic",
      "percentage""0%"
    },


...
 
   {
      "repoKey""TOTAL",
      "repoType""NA",
      "foldersCount"92172,
      "filesCount"2084408,
      "usedSpace""59.77 GB",
      "itemsCount"2176580
    }
  ]
}



File Statistics

Description: Item statistics record the number of times an item was downloaded, last download date and last downloader. Supported by local and local-cached repositories.
Security:
 Requires read privileges
Usage:
 GET /api/storage/{repoKey}/{item-path}?stats
Produces: application/json (application/vnd.org.jfrog.storage.StatsInfo+json)
Sample Output:

GET /api/storage/libs-release-local/org/acme/foo/1.0/foo-1.0.jar?stats
{
  "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/foo/1.0/foo-1.0.jar",
  "lastDownloaded": Timestamp (ms),
  "downloadCount": 1337,
  "lastDownloadedBy": "user1"
}

Item Properties

Description: Item Properties. Optionally return only the properties requested.
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/storage/{repoKey}/{itemPath}?properties[=x[,y]]
Produces: application/json (application/vnd.org.jfrog.artifactory.storage.ItemProperties+json)
Sample Output:

GET /api/storage/libs-release-local/org/acme?properties\[=x[,y]\]
{
"uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme"
"properties":{
        "p1": ["v1","v2","v3"],
        "p2": ["v4","v5","v6"]
    }
}


Set Item SHA256 Checksum

Description: Calculates an artifact's SHA256 checksum and attaches it as a property (with key "sha256"). If the artifact is a folder, then recursively calculates the SHA256 of each item in the folder and attaches the property to each item.
Security: Requires an admin user
Consumes: application/json
Usage: POST /api/checksum/sha256 -H "Content-Type: application/json"
Sample Usage: 

POST /api/checksum/sha256 -H "Content-Type: application/json"
{
   "repoKey":"ext-snapshot-local",
   "path":"artifactory-powerpack-3.9.3/bin/"
}

Retrieve Artifact

Description: Retrieves an artifact from the specified destination.
You can also use Property-based Resolution as part of retrieving artifacts.
Security: Requires a user with 'read' permission (can be anonymous)
Usage: GET /repo-key/path/to/artifact.ext
Sample Usage:

GET http://localhost:8081/artifactory/libs-release-local/ch/qos/logback/logback-classic/0.9.9/logback-classic-0.9.9.jar

Trace Artifact Retrieval

Description: Simulates an artifact retrieval request from the specified location and returns verbose output about the resolution process.
This API is useful for debugging artifact retrieval issues. 
Security: As applied to standard artifact retrieval by the requesting user.
Usage: GET /repo-key/path/to/artifact.ext?trace
Produces: text/plain
Sample Output:

GET http://localhost:8081/artifactory/libs-release-local/jmock/jmock/1.0.1/jmock-1.0.1.jar?trace
 
Request ID: 51c808f6
Repo Path ID: libs-release-local:jmock/jmock/1.0.1/jmock-1.0.1.jar
Method Name: GET
User: resolver
Time: 2012-05-06T10:49:09.528+03:00
Thread: pool-1-thread-31
Steps: 
2012-05-06T10:49:09.587+03:00 Received request
2012-05-06T10:49:09.588+03:00 Request source = 0:0:0:0:0:0:0:1, Last modified = 01-01-70 01:59:59 IST, If modified since = -1, Thread name = pool-1-thread-31
2012-05-06T10:49:09.697+03:00 Retrieving info
2012-05-06T10:49:09.723+03:00 Identified resource as a file
...
2012-05-06T10:49:09.788+03:00 Responding with selected content handle
2012-05-06T10:49:09.807+03:00 Request succeeded

Archive Entry Download

Description: Retrieves an archived resource from the specified archive destination.
Security: Requires a user with 'read' permission (can be anonymous)
Usage: GET /repo-key/path/to/artifact.jar!/path/to/archived/resource (NOTE! the '!' should be in between the archive file name and the archive entry path, and will not work without the '/' after the '!'.)

Sample Output:

GET http://localhost:8081/artifactory/repo1-cache/commons-lang/commons-lang/2.6/commons-lang-2.6.jar!/META-INF/LICENSE.txt

Create Directory

Description: Create new directory at the specified destination.
Notes: You can also attach properties as part of creating directories.
Security: Requires a user with 'deploy' permissions (can be anonymous)
Usage: PUT /repo-key/path/to/directory/
Produces: application/json (application/vnd.org.jfrog.artifactory.storage.ItemCreated+json)
Sample Usage:

PUT /libs-release-local/path/to/directory/
{
"uri": "http://localhost:8081/artifactory/libs-release-local/path/to/directory",
"repo": "libs-release-local",
"path": "/path/to/directory",
"created": ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"createdBy": "userY",
"children" : [ ]
}

Deploy Artifact

Description: Deploy an artifact to the specified destination.
Notes: You can also attach properties as part of deploying artifacts.
Security: Requires a user with 'deploy' permissions (can be anonymous)
Usage: PUT /repo-key/path/to/artifact.ext
Produces: application/json (application/vnd.org.jfrog.artifactory.storage.ItemCreated+json)
Sample Usage:

PUT /libs-release-local/my/jar/1.0/jar-1.0.jar
{
"uri": "http://localhost:8081/artifactory/libs-release-local/my/jar/1.0/jar-1.0.jar",
"downloadUri": "http://localhost:8081/artifactory/libs-release-local/my/jar/1.0/jar-1.0.jar",
"repo": "libs-release-local",
"path": "/my/jar/1.0/jar-1.0.jar",
"created": ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"createdBy": "userY",
"size": "1024", //bytes
"mimeType": "application/java-archive",
"checksums":
{
        "md5" : string,
        "sha1" : string
    },
"originalChecksums":{
        "md5" : string,
        "sha1" : string
    }
}

Deploy Artifact by Checksum

Description: Deploy an artifact to the specified destination by checking if the artifact content already exists in JFrog Container Registry.
If JFrog Container Registry already contains a user readable artifact with the same checksum the artifact content is copied over to the new location and return a response without requiring content transfer.
Otherwise, a 404 error is returned to indicate that content upload is expected in order to deploy the artifact.
Notes: You can also attach properties as part of deploying artifacts. 
Security: Requires a user with 'deploy' permissions (can be anonymous)
Usage: PUT /repo-key/path/to/artifact.ext
Headers: X-Checksum-Deploy: true, X-Checksum-Sha1: sha1Value, X-Checksum-Sha256: sha256Value, X-Checksum: checksum value (type is resolved by length)
Produces: application/json (application/vnd.org.jfrog.artifactory.storage.ItemCreated+json)
Sample Output:

PUT /libs-release-local/my/jar/1.0/jar-1.0.jar
{
"uri": "http://localhost:8081/artifactory/libs-release-local/my/jar/1.0/jar-1.0.jar",
"downloadUri": "http://localhost:8081/artifactory/libs-release-local/my/jar/1.0/jar-1.0.jar",
"repo": "libs-release-local",
"path": "/my/jar/1.0/jar-1.0.jar",
"created": ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"createdBy": "userY",
"size": "1024", //bytes
"mimeType": "application/java-archive",
"checksums":
{
        "md5" : string,
        "sha1" : string
    },
"originalChecksums":{
        "md5" : string,
        "sha1" : string
    }
}


Push Docker Tag to Bintray

Description: Push Docker tag to Bintray
Calculation can be synchronous (the default) or asynchronous.
Security: Requires a valid user with deploy permissions and Bintray credentials defined (for more details, please refer to Bintray Settings).
Usage: POST /api/bintray/docker/push/{repoKey}
Produces: text/plain

Sample Output:

POST api/bintray/docker/push/docker-local
{
  "dockerImage": "jfrog/ubuntu:latest", // The docker image to push, use ':' for specific tag or leave blank for 'latest'
  "bintraySubject": "shayy", // The Bintray Subject
  "bintrayRepo": "containers", // The Bintray Subject's repository
  "async": false // Optionally execute the push asynchronously. Default: false
}

Delete Item

Description: Deletes a file or a folder from the specified local repository or remote repository cache.
Security: Requires a user with 'delete' permission (can be anonymous)
Usage: DELETE /repo-key/path/to/file-or-folder
Sample Usage:

DELETE http://localhost:8081/artifactory/libs-release-local/ch/qos/logback/logback-classic/0.9.9

Get Background Tasks

Description: Retrieves list of background tasks currently scheduled or running in JFrog Container Registry. Task can be in one of few states: scheduled, running, stopped, cancelled. Running task also shows the task start time.
Security: Requires a valid admin user
Usage: GET /api/tasks
Produces: application/json
Sample Output

{ 
   "tasks":[ 
      { 
         "id":"artifactory.StatsPersistingServiceFlushJob#c52c9576-ae9b-4e7a-a0e5-01aab05a04b2",
         "type":"org.artifactory.storage.jobs.StatsPersistingServiceFlushJob",
         "state":"scheduled",
         "description":"Download Statistics Flushing"
      },
      { 
         "id":"artifactory.VirtualCacheCleanupJob#82bb1514-ea34-4a71-940d-78a61887981e",
         "type":"org.artifactory.repo.cleanup.VirtualCacheCleanupJob",
         "state":"scheduled",
         "description":""
      },
      { 
         "id":"artifactory.BinaryStoreGarbageCollectorJob#039664ac-990d-4a32-85e1-decd0b508142",
         "type":"org.artifactory.storage.binstore.service.BinaryStoreGarbageCollectorJob",
         "state":"running",
         "started":"2015-05-15T15:39:37.566+02:00",
         "description":"Binaries Garbage Collector"
      }
   ]
}

Run Garbage Collection

Description: Run Garbage Collection
Security: Requires an admin user.
Usage: POST /api/system/storage/gc
Produces: text/plain
Sample Usage:

POST /api/system/storage/gc

200 OK

Optimize System Storage

Description: Raises a flag to invoke balancing between redundant storage units of a sharded filestore following the next garbage collection.
Notes: This is an advanced feature intended for administrators. 
Security: Requires a valid admin user.
Usage: POST /api/system/storage/optimize
Produces: text/plain
Sample Usage:

POST /api/system/storage/optimize

200 OK

SEARCHES

All searches return limited results for internal and anonymous users (same limits as in the user interface).

To modify the default limit results, edit the artifactory.system.properties file with artifactory.search.limitAnonymousUsersOnly=false (default is true) and add a new limit with artifactory.search.userQueryLimit  (default is 1000).

Applicable to the following REST API calls:
Artifact Search, Archive Entries Search, Property Search, Checksum Search (limited by UI max results), Artifacts Not Downloaded SinceArtifacts With Date in Date Range, Artifacts Created in Date Range.

Artifactory Query Language (AQL)

Description: Flexible and high performance search using Artifactory Query Language (AQL).
Security: Requires an authenticated user. Certain domains/queries may require Admin access.
Usage: POST /api/search/aql
Consumes: text/plain
Sample Usage:


POST /api/search/aql  
items.find(
	{
		"repo":{"$eq":"libs-release-local"}
	}
)

Produces: application/json
Sample Output:

{
	"results" : [
  	{
 		"repo" : "libs-release-local",
 		"path" : "org/jfrog/artifactory",
		"name" : "artifactory.war",
 		"type" : "item type",
 		"size" : "75500000",
 		"created" : "2015-01-01T10:10;10",
 		"created_by" : "Jfrog",
 		"modified" : "2015-01-01T10:10;10",
 		"modified_by" : "Jfrog",
 		"updated" : "2015-01-01T10:10;10"
	}
	],
	"range" : {
 	"start_pos" : 0,
 	"end_pos" : 1,
 	"total" : 1
	}
}

The range describes the number of results returned by the query, where start_pos is the first index of the first result, and end_pos is the index+1 of the last result. For this reason, end_pos will always be the same value as total, the total number of results returned.


Artifact Search (Quick Search)

Description: Artifact search by part of file name.
Searches return file info URIs. Can limit search to specific repositories (local or caches).
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/search/artifact?name=name[&repos=x[,y]]
Headers (Optionally): X-Result-Detail: info (To add all extra information of the found artifact), X-Result-Detail: properties (to get the properties of the found artifact), X-Result-Detail: info, properties (for both).
Produces: application/json (application/vnd.org.jfrog.artifactory.search.ArtifactSearchResult+json)
Sample Output:

GET /api/search/artifact?name=lib&repos=libs-release-local
{
"results": [
{
            "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver/lib-ver.pom"
        },{
            "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver2/lib-ver2.pom"
        }
]
}

Archive Entries Search (Class Search)

Description: Search archive for classes or any other resources within an archive.
Can limit search to specific repositories (local or caches).
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/search/archive?name=[archiveEntryName][&repos=x[,y]]
Produces: application/json (application/vnd.org.jfrog.artifactory.search.ArchiveEntrySearchResult+json)
Sample Output:

GET /api/search/archive?name=*Logger.class&repos=third-party-releases-local,repo1-cache
{
"results" :[
    {
        "entry": "org/apache/jackrabbit/core/query/lucene/AbstractIndex.LoggingPrintStream.class",
        "archiveUris": [
            "http://localhost:8081/artifactory/api/storage/third-party-releases-local/org/apache/jackrabbit/
                    jackrabbit-core/1.2.3/jackrabbit-core-1.2.3.jar",
            "http://localhost:8081/artifactory/api/storage/third-party-releases-local/org/apache/jackrabbit/
                    jackrabbit-core/1.3.1/jackrabbit-core-1.3.1.jar"
        ]
        },{
            "entry": "org/codehaus/plexus/logging/AbstractLogger.class",
            "archiveUris": [
                 "http://localhost:8081/artifactory/api/storage/repo1-cache/org/codehaus/plexus/plexus-container-default/
                        1.0-alpha-9-stable-1/plexus-container-default-1.0-alpha-9-stable-1.jar"
            ]
        }
    ]
}


Property Search

Description: Search by properties.
If no value is specified for a property - assume '*'. Can limit search to specific repositories (local, remote-cache or virtual).
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/search/prop?[p1=v1,v2][&p2=v3][&repos=x[,y]]
Headers (Optionally): X-Result-Detail: info (To add all extra information of the found artifact), X-Result-Detail: properties (to get the properties of the found artifact), X-Result-Detail: info, properties (for both).
Produces: application/json (application/vnd.org.jfrog.artifactory.search.MetadataSearchResult+json)
Sample Output:

GET /api/search/prop?p1=v1,v2&p2=v3&repos=libs-release-local
{
"results" : [
    {
        "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver/lib-ver.pom"
    },{
        "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver2/lib-ver2.pom"
    }
]
}

Artifacts Not Downloaded Since

Description: Retrieve all artifacts not downloaded since the specified Java epoch in milliseconds.
Optionally include only artifacts created before the specified createdBefore date, otherwise only artifacts created before notUsedSince are returned.
Can limit search to specific repositories (local or caches).
Security: Requires a privileged non-anonymous user.
Usage: GET /api/search/usage?notUsedSince=javaEpochMillis[&createdBefore=javaEpochMillis][&repos=x[,y]]
Produces: application/json (application/vnd.org.jfrog.artifactory.search.ArtifactUsageResult+json)
Sample Output:

GET /api/search/usage?notUsedSince=long&createdBefore=long&repos=libs-release-local
{
"results" : [
    {
        "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver/lib-ver.jar",
        "lastDownloaded": ISO8601
    },{
        "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver2/lib-ver2.jar",
        lastDownloaded: ISO8601
    }
]
}

Artifacts With Date in Date Range

Description: Get all artifacts with specified dates within the given range. Search can be limited to specific repositories (local or caches).
Security: Requires a privileged non-anonymous user.
Usage: GET /api/search/dates?[from=fromVal][&to=toVal][&repos=x[,y]][&dateFields=c[,d]]
Parameters: The from and to parameters can be either a long value for the java epoch (milliseconds since the epoch), or an ISO8601 string value. from is mandatory. If to is not provided, now() will be used instead, and if either are omitted, 400 bad request is returned.
The dateFields parameter is a comma separated list of date fields that specify which fields the from and to values should be applied to. The date fields supported are: created, lastModified, lastDownloaded.
It is a mandatory field and it also dictates which fields will be added to the JSON returned.
If ANY of the specified date fields of an artifact is within the specified range, the artifact will be returned.

Produces: application/json (application/vnd.org.jfrog.artifactory.search.ArtifactResult+json)

Sample Output:

GET /api/search/dates?dateFields=created,lastModified,lastDownloaded&from=long&to=long&repos=libs-release-local
{
"results" : [
    {
        "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver/lib-ver.jar",
        "created": ISO8601,
        "lastModified": ISO8601,
        "lastDownloaded": ISO8601
    },{
        "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver2/lib-ver2.jar",
        "created": ISO8601.
        "lastModified": ISO8601,
        "lastDownloaded": ISO8601
    }
]
}

Artifacts Created in Date Range

Description: Get All Artifacts Created in Date Range
If 'to' is not specified use now(). Can limit search to specific repositories (local or remote-cache).
Security: Requires a privileged non-anonymous user.
Usage: GET /api/search/creation?from=javaEpochMillis[&to=javaEpochMillis][&repos=x[,y]]
Produces: application/json (application/vnd.org.jfrog.artifactory.search.ArtifactCreationResult+json)
Sample Output:

GET /api/search/creation?from=long&to=long&repos=libs-release-local
{
"results" : [
    {
        "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver/lib-ver.jar",
        "created": ISO8601
    },{
        "uri": "http://localhost:8081/artifactory/api/storage/libs-release-local/org/acme/lib/ver2/lib-ver2.jar",
        "created": ISO8601
    }
]
}

List Docker Repositories

Description: Lists all Docker repositories (the registry's _catalog) hosted in an JFrog Container Registry Docker repository.
NotesTo enable fetch from cache using the ListDockerRepositories and the ListDockerTags rest APIs, set the artifactory.docker.catalogs.tags.fallback.fetch.remote.cache system property to true (default false) in the artifactory.system.properties file.
Security: Requires a privileged user
Usage: GET /api/docker/{repo-key}/v2/_catalog?n=<n from the request>&last=<last tag value from previous response>
Produces: application/json

{
  "repositories": [
    <name>,
    ...
  ]
}

Sample Usage:

GET /api/docker/docker-local/v2/_catalog
{
  "repositories": [
    "busybox",
    "centos",
    "hello-world"
  ]
}

List Docker Tags

Description: Lists all tags of the specified JFrog Container Registry Docker repository.
Notes: To enable fetch from cache using the ListDockerRepositories and the ListDockerTags rest APIs, set the artifactory.docker.catalogs.tags.fallback.fetch.remote.cache system property to true (default false) in the artifactory.system.properties file.
Security: Requires a privileged user
Usage: GET /api/docker/{repo-key}/v2/{image name}/tags/list?n=<tag for the specified Docker Image>&last=<Number of consecutive tags>
Produces: application/json

{
  "name": "<image name>",
  "tags" : ["<tag>"]
}

Sample Usage:

GET api/docker/v2/postgres/tags/list
{
  "name" : "postgres",
  "tags" : [ "9.5.2" ]
}

SECURITY

Get User Encrypted Password

Description: Get the encrypted password of the authenticated requestor. 
Notes: The request needs to be authenticated using a clear-text password. i.e. when submitting the request to JFrog Container Registry, the password provided for authentication needs to be in clear-text. If you authenticate with an API key, the encrypted API key will be returned in the response.
Security: Requires a privileged user
Usage: GET /api/security/encryptedPassword
Produces: plain/text
Sample Output:

GET /api/security/encryptedPassword

AP5v2zs9ga7CJNZb74u3arAKE5B

Configure User Lock Policy

Description: Configures the user lock policy that locks users out of their account if the number of repeated incorrect login attempts exceeds the configured maximum allowed.
Security: Requires a valid admin user
Usage: PUT /api/security/userLockPolicy
Produces: application/text
Sample usage:

PUT http://{host}:{port}/artifactory/api/security/userLockPolicy -H 'Content-Type: application/json'-d '
{ 
   "enabled" : true|false, 
   "loginAttempts" : {value} 
}'

Retrieve User Lock Policy

Description: Retrieves the currently configured user lock policy.
Security: Requires a valid admin user 
Usage: GET /api/security/userLockPolicy 
Produces: application/json
Sample usage:

GET http://{host}:{port}/artifactory/api/security/userLockPolicy
'{ 
   "enabled" : true|false, 
   "loginAttempts" : {value} 
}'

Get Locked Out Users

Description: If locking out users is enabled, lists all users that were locked out due to recurrent incorrect login attempts.
Security: Requires a valid admin user
Usage: GET /api/security/lockedUsers
Produces: application/json
Sample Usage:

GET /api/security/lockedUsers
 
[ "usera", "userb",  ... ]

Unlock Locked Out User

Description: Unlocks a single user that was locked out due to recurrent incorrect login attempts.

Security:  Requires a valid admin user
Usage: POST /api/security/unlockUsers/{userName}
Produces:  application/text
Sample Usage:

POST /api/security/unlockUsers/{userName}

 


Unlock Locked Out Users

Description: Unlocks a list of users that were locked out due to recurrent incorrect login attempts.

Security:  Requires a valid admin user
Usage: POST /api/security/unlockUsers
Produces:  application/tex
Sample Usage:


POST /api/security/unlockUsers -H 'Content-Type: application/json' -d '[ {userA}, {userB} ]'

Unlock All Locked Out Users 

Description: Unlocks all users that were locked out due to recurrent incorrect login attempts.

Security:  Requires a valid admin user
Usage: POST /api/security/unlockAllUsers
Produces:  application/text
Sample Usage:
POST /api/security/unlockAllUsers



Create API Key

Description:Create an API key for the current user. Returns an error if API key already exists - use regenerate API key instead.
Usage: POST /api/security/apiKey
Produces: application/json
Sample input:

POST /api/security/apiKey

Sample output:

{
    "apiKey": "3OloposOtVFyCMrT+cXmCAScmVMPrSYXkWIjiyDCXsY="
}

Regenerate API Key

Description:Regenerate an API key for the current user
Usage: PUT /api/security/apiKey
Produces: application/json
Sample input:

PUT /api/security/apiKey

Sample output:

{
    "apiKey": "3OloposOtVFyCMrT+cXmCAScmVMPrSYXkWIjiyDCXsY="
}

Get API Key

Description:Get the current user's own API key
Usage: GET /api/security/apiKey
Produces: application/json

Sample usage:

GET /api/security/apiKey

Sample output:

{
    "apiKey": "3OloposOtVFyCMrT+cXmCAScmVMPrSYXkWIjiyDCXsY="
}

Revoke API Key

Description: Revokes the current user's API key
Usage: DELETE /api/security/apiKey
Produces: application/json


Revoke User API Key

Description: Revokes the API key of another user
Security: Requires a privileged user (Admin only)
Usage
: DELETE /api/security/apiKey/{username} 
Produces: application/json


Revoke All API Keys

Description: Revokes all API keys currently defined in the system
Security: Requires a privileged user (Admin only)
Usage
: DELETE /api/security/apiKey?deleteAll={0/1} 
Produces: application/json


Activate JFrog Container Registry Key Encryption

Description: Creates a new JFrog Container Registry encryption key and activates JFrog Container Registry key encryption.
Notes: This is an advanced feature intended for administrators
Security: Requires a valid admin user
Usage: POST /api/system/encrypt
Produces: text/plain
Sample Usage:

POST /api/system/encrypt

DONE

Deactivate JFrog Container Registry Key Encryption

Description: Removes the current JFrog Container Registry encryption key and deactivates JFrog Container Registry key encryption.
Notes: This is an advanced feature intended for administrators
Security: Requires a valid admin user
Usage: POST /api/system/decrypt
Produces: text/plain
Sample Usage:

POST /api/system/decrypt

DONE


Create Token

Description: Creates an access token
Security: Requires a valid user
Usage
: POST /api/security/token
Content-Type: application/x-www-form-urlencoded 

Produces: application/json

{
   "access_token":   "<the access token>",
   "expires_in":    <Validity period in seconds>,
   "scope":         "<access scope>",
   "token_type":    "Bearer",
   "refresh_token": "<the refresh token if access_token is refreshable>"
}

Sample Usage:

curl -uadmin:password -XPOST "http://localhost:8081/artifactory/api/security/token" -d "username=johnq" -d "scope=member-of-groups:readers"
 
200
{
   "access_token":   "adsdgbtybbeeyh...",
   "expires_in":    3600,
   "scope":         "api:* member-of-groups:readers",
   "token_type":    "Bearer",
   "refresh_token": "fgsfgsdugh8dgu9s8gy9hsg..."
}

This endpoint takes the following parameters:

grant_type

[Optional, default: "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

The user name for which this token is created. If the user does not exist, a transient user is created. Non-admin users can only create tokens for themselves so they must specify their own username.

If the user does not exist, the member-of-groups scope token must be provided (e.g. member-of-groups: g1, g2, g3...)

scope

The scope to assign to the token provided as a space-separated list of scope tokens. Currently there are three possible scope tokens:

  • "api:*" - indicates that the token grants access to REST API calls. This is always granted by default whether specified in the call or not.
  • member-of-groups:[<group-name>] - indicates the groups that the token is associated with (e.g. member-of-groups: g1, g2, g3...). The token grants access according to the permission targets specified for the groups listed.

     If any of the group names includes a space character, the whole value should be enclosed in escaped quotation marks. For example:

    scope=member-of-groups:\"readers,test group\"

    Specify "*" for group-name to indicate that this is a "user-scoped token", i.e., the token provides the same access privileges that the current subject, as specified in the username parameter, has, and is therefore evaluated dynamically.
    A non-admin user can only provide a scope that is a subset of the groups to which he belongs

  • "jfrt@<instance-id>:admin" - provides admin privileges on the specified Artifactory instance. This is only available for administrators.


expires_in

[Optional, default: 3600]

The time in seconds for which the token will be valid. To specify a token that never expires, set to zero. Non-admin can only set a value that is equal to or less than the default 3600.

refreshable

[Optional, default: false]

If true, this token is refreshable and the refresh token can be used to replace it with a new token once it expires.

audience

[Optional, default: Only the service ID of the Artifactory instance that created the token]

A space-separate list of the other Artifactory instances or services that should accept this token identified by their Artifactory Service IDs as obtained from the Get Service ID endpoint.

In case you want the token to be accepted by all Artifactory instances you may use the following audience parameter "audience=jfrt@*".




Refresh Token

Description: Refresh an access token to extend its validity. If only the access token and the refresh token are provided (and no other parameters), this pair is used for authentication. If username or any other parameter is provided, then the request must be authenticated by a token that grants admin permissions.
Security: Requires a valid user (unless both access token and refresh token are provided)
Usage: POST /api/security/token

Content-Type: application/x-www-form-urlencoded

Produces: application/json (Please refer to Create Token)

Sample Usage: 

curl -XPOST "http://localhost:8081/artifactory/api/security/token" -d "grant_type=refresh_token" -d "refresh_token=fgsg53t3g…" -d "access_token=gsfdgw35gt..."
 
200 (Success) As in Create Token
 
400 (Error) If the token was created by a different Artifactory instance (and hence cannot be refreshed)

This endpoint takes the following parameters:

grant_type

Should be set to refresh_token.

refresh_token
The refresh token of the access token that needs to be refreshed.
access_token

The access token to refresh.

username

Please refer to Create Token.

Note: access_token and username are mutually exclusive, so only one of these parameters should be specified.

If access_token is provided, the new token is created with the same settings as that token.


scope
expires_in
refreshable
audience

Get Tokens

Description: Get a list of all tokens created by an JFrog Container Registry instance
Security: Requires an admin user
Usage: GET /api/security/token
Content-Type: application/x-www-form-urlencoded

Produces: application/json 


{
  "tokens":[
    {
      "token_id":"<the token id>",
      "issuer":"<the service ID of the issuing JFrog Container Registry instance>",
      "subject":"<subject>",
      "expiry": <time when token expires as seconds since 00:00:00 1/1/1970>,
      "refreshable":<true | false>,
      "issued_at":<time issued as seconds since 00:00:00 1/1/1970>,
    }, ...
  ]
}



Sample Usage:

curl -uadmin:password -XGET "http://localhost:8081/artifactory/api/security/token

 
200 OK
{
  "tokens":[
    {
      "token_id":"123",
      "issuer":"jf-artifactory@123123",
      "subject":"jf-artifactory@123123/users/theusername",
      "expiry":145154545,
      "refreshable":true,
      "issued_at":144152345
    }, ...
  ]
}

Revoke Token

Description: Revoke an access token by specifying the token or the token_id
Security: Requires an admin user
Usage: POST /api/security/token/revoke
Content-Type: application/x-www-form-urlencoded

Produces: application/json 
Sample Usage:

curl -uadmin:password -XPOST "http://localhost:8081/artifactory/api/security/token/revoke" -d "token=fasdt3..."
or
curl -uadmin:password -XPOST "http://localhost:8081/artifactory/api/security/token/revoke" -d "token_id=7e0eec..."
 
200 OK (Also returned if the token was already revoked or non-existent)
 
400 (Error) If the token was created by a different JFrog Container Registry instance (and hence cannot be revoked)

This endpoint can take either of the following parameters:

token

The token to be revoked

token_id
The ID of the token to be revoked

Get Service ID

Description: Provides the service ID of an JFrog Container Registry instance or cluster. The JFrog Container Registry service ID is formatted jfrt@<id>.
Security: Requires an admin user
Usage: GET /api/system/service_id
Produces: text/plain
Sample Usage:

curl -uadmin:password -XGET "http://localhost:8081/artifactory/api/system/service_id"
 
200
jfrt@ee27b1d1-534d-4723-80b5-5bd893d19c43



REPOSITORIES

Get Repositories

Description: Returns a list of minimal repository details for all repositories of the specified type.
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/repositories[?type=repositoryType (local|remote|virtual|distribution)][&packageType=helm|helm|docker|generic]
Produces: application/json (application/vnd.org.jfrog.artifactory.repositories.RepositoryDetailsList+json)

Sample Output:

GET /api/repositories
[ {
  "key" : "docker-local",
  "type" : "LOCAL",
  "url" : "http://localhost:8080/artifactory/docker-local",
  "packageType" : "Docker"
}, {
  "key" : "helm-local",
  "type" : "LOCAL",
  "url" : "http://localhost:8080/artifactory/helm-local",
  "packageType" : "Helm"
}, {
  "key" : "bintray-docker-remote",
  "type" : "REMOTE",
  "url" : "https://docker.bintray.io",
  "packageType" : "Docker"
}, {
  "key" : "docker-remote",
  "type" : "REMOTE",
  "url" : "https://registry-1.docker.io/",
  "packageType" : "Docker"
}]

Calculate Helm Chart Index

Description: Calculates Helm chart index on the specified path (local repositories only).
Security: Requires the set of permissions assumed by Manage (Manage + Delete/Overwrite + Deploy/Cache + Annotate + Read)
Usage: POST /api/helm/{repoKey}/reindex
Produces: application/text
Sample Usage:

POST /api/helm/helm-local/reindex
OK

SYSTEM & CONFIGURATION

System Info

Description: System Info
Get general system information.
Security: Requires a valid admin user
Usage: GET /api/system
Produces: text/plain
Sample Output:

GET /api/system

system info output text

System Health Ping

Description: Get a simple status response about the state of JFrog Container Registry.
Returns 200 code with an 'OK' text if JFrog Container Registry is working properly, if not will return an HTTP error code with a reason.
Security: Requires a valid user (can be anonymous).  If artifactory.ping.allowUnauthenticated=true is set in artifactory.system.properties, then no authentication is required even if anonymous access is disabled.
Usage: GET /api/system/ping
Produces: text/plain
Sample Output:

GET /api/system/ping
OK

Verify Connection

Description: Verifies a two-way connection between JFrog Container Registry and another product
Returns Success (200) if JFrog Container Registry receives a similar success code (200) from the provided endpoint. See possible error codes below.
Security: Requires an admin user.
Usage: POST/api/system/verifyconnection
Consumes: application/json


POST /api/system/verifyconnection
{
  +  "endpoint" : "<The URL that JFrog Container Registry should connect to>",
  -  "username" : "<Username to be used for the connection test>",
  -  "password" : "<Password to be used for the connection test>"
}

Produces: application/json

Upon success (200):
200 Successfully connected to endpoint
 
Upon error, returns 400 along with a JSON object that contains the error returned from the other system.


Sample Output:

{
  "errors" : [ {
    "status" : 400,
    "message" : "Received error from endpoint url: HTTP 404: Page not found"
  } ]
}

General Configuration

Description: Get the general configuration (artifactory.config.xml).
Security: Requires a valid admin user
Usage: GET /api/system/configuration
Produces: application/xml (http://www.jfrog.org/xsd/artifactory-v1_7_3.xsd)
Sample Output:

GET /api/system/configuration

<artifactory.config.xml/>

Save General Configuration

Description: Save the general configuration (artifactory.config.xml).
Notes: This is an advanced feature - make sure the new configuration is really what you wanted before saving.
Security: Requires a valid admin user
Usage: POST /api/system/configuration
Consumes: application/xml (http://www.jfrog.org/xsd/artifactory-v1_7_3.xsd)
Sample Usage:

POST /api/system/configuration

<artifactory.config.xml/>

Update Custom URL Base

Description: Changes the Custom URL base
Security: Requires a valid admin user
Usage: PUT /api/system/configuration/baseUrl
Example: curl -X PUT "http://localhost:8081/artifactory/api/system/configuration/baseUrl" -d 'https://mycompany.com:444/artifactory' -uadmin:password -H "Content-type: text/plain" 
Sample Output:

URL base has been successfully updated to "https://mycompany.com:444/artifactory".

License Information

Description: Retrieve information about the currently installed license.
Security: Requires a valid admin user
Usage: GET /api/system/licenses
Produces: application/json
Sample Output:

GET /api/system/licenses
{
  "type" : "Commercial",
  "validThrough" : "May 15, 2014",
  "licensedTo" : "JFrog inc."
}

Install License

Description: Install new license key or change the current one.
Security: Requires a valid admin user
Usage: POST /api/system/licenses
Consumes: application/json

POST /api/system/licenses
{ 
	"licenseKey": "<supplied license key>"         // Any newline characters must be represented by escape sequence (\n)
}

Produces: application/json
Sample Output:

POST /api/system/licenses
{
  "status" : 200,
  "message" : "The license has been successfully installed."
}

Version and Add-ons information

Description: Retrieve information about the current JFrog Container Registry version, revision, and currently installed Add-ons
Security: Requires a valid user (can be anonymous)
Usage: GET /api/system/version
Producesapplication/json (application/vnd.org.jfrog.artifactory.system.Version+json)
Sample Output:

GET /api/system/version
{
  "version" : "2.2.2",
  "revision" : "10427",
  "addons" : [ "build", "ldap", "properties", "rest", "search", "sso", "watch", "webstart" ]
}

Get Reverse Proxy Configuration

Description: Retrieves the reverse proxy configuration
Security: Requires a valid admin user
UsageGET /api/system/configuration/webServer
Produces: application/json
Sample Output:

GET /api/system/configuration/webServer

{
  "key" : "nginx",
  "webServerType" : "NGINX",
  "artifactoryAppContext" : "artifactory",
  "publicAppContext" : "artifactory",
  "serverName" : "jfrog.com",
  "serverNameExpression" : "*.jfrog.com",
  "artifactoryServerName" : "localhost",
  "artifactoryPort" : 8081,
  "sslCertificate" : "/etc/ssl/myKey.cert",
  "sslKey" : "/etc/ssl/myKey.key",
  "dockerReverseProxyMethod" : "SUBDOMAIN",
  "useHttps" : true,
  "useHttp" : true,
  "sslPort" : 443,
  "httpPort" : 76
}

Update Reverse Proxy Configuration

Description: Updates the reverse proxy configuration
Security: Requires an admin user
Usage: POST /api/system/configuration/webServer
Consumesapplication/json
Sample Usage:

POST /api/system/configuration/webServer
{
  "key" : "nginx",
  "webServerType" : "NGINX",
  "artifactoryAppContext" : "artifactory",
  "publicAppContext" : "artifactory",
  "serverName" : "jfrog.com",
  "serverNameExpression" : "*.jfrog.com",
  "artifactoryServerName" : "localhost",
  "artifactoryPort" : 8081,
  "sslCertificate" : "/etc/ssl/myKey.cert",
  "sslKey" : "/etc/ssl/myKey.key",
  "dockerReverseProxyMethod" : "SUBDOMAIN",
  "useHttps" : true,
  "useHttp" : true,
  "sslPort" : 443,
  "httpPort" : 76
}

Get Reverse Proxy Snippet

Description: Gets the reverse proxy configuration snippet in text format
Security: Requires a valid user (not anonymous)
Usage: GET /api/system/configuration/reverseProxy/nginx
Producestext/plain
Sample Usage:

GET /api/system/configuration/reverseProxy/nginx
 
## add ssl entries when https has been set in config
ssl_certificate      /etc/ssl/myKey.cert;
ssl_certificate_key  /etc/ssl/myKey.key;
ssl_session_cache shared:SSL:1m;
ssl_prefer_server_ciphers   on;
## server configuration
server {
    listen 443 ssl;
    listen 76 ;
    server_name ~(?<repo>.+)\.jfrog.com jfrog.com;
    
    if ($http_x_forwarded_proto = '') {
        set $http_x_forwarded_proto  $scheme;
    }
    ## Application specific logs
    ## access_log /var/log/nginx/jfrog.com-access.log timing;
    ## error_log /var/log/nginx/jfrog.com-error.log;
    rewrite ^/$ /artifactory/webapp/ redirect;
    rewrite ^/artifactory$ /artifactory/webapp/ redirect;
}

Start SHA256 Migration Task

Description: Starts the SHA-256 migration process.
Note: Migration can also be configured using a set of properties in artifactory.system.properties file.
Security: Administrator permissions
Usage: POST api/system/migration/sha2/start 
Consumesapplication/json

{
  - "batchThreshold":10 (default),
  - "queryLimit":100 (default),
  - "waitForClusterSleepIntervalMillis":5000 (default),
  - "sleepIntervalMillis":5000 (default),
  - "forceRunOnNodeId":""
}

Produces: text/plain
Sample Output
:

Sha256 migration scheduled to start successfully

Stop SHA256 Migration Task

Description: Stops the SHA-256 migration process
Security: Administrator permissions
Note: The sleepIntervalMillis should match what was defined in the Start SHA256 Migration Task
Usage: POST api/system/migration/sha2/stop?{sleepIntervalMillis=5000} 
Producestext/plain
Sample Output:

Sha256 migration scheduled to stop successfully.

IMPORT & EXPORT

Import Repository Content

Description: Import one or more repositories.
Security: Requires a valid admin user
Usage: POST: /api/import/repositories
Requests Params:
path - The file system path to import from. This may point to a specific folder to import data for a single repository, or to the parent "repositories" folder to import data for all repositories.
repo - Empty/null repo -> all
metadata - Include metadata - default 1
verbose - Verbose - default 0
Produces: text/plain
Sample Output:

POST: /api/import/repositories?path=pathToRepos&verbose=1

Import System Settings Example

Description: Returned default Import Settings JSON. JFrog Container Registry maintains any security entities (users, groups, permissions and tokens) when doing a system import.
Security: Requires a valid admin user
Usage: GET: /api/import/system
Producesapplication/json (application/vnd.org.jfrog.artifactory.system.ImportSettings+json)
Sample Usage:

GET /api/import/system
{
  "importPath" : "/import/path",
  "includeMetadata" : true,
  "verbose" : false,
  "failOnError" : true,
  "failIfEmpty" : true
}

Full System Import

Description: Import full system from a server local JFrog Container Registry export directory. JFrog Container Registry maintains any security entities (users, groups, permissions and tokens) when doing a system import.
Security: Requires a valid admin user
Usage: POST: /api/import/system
Consumesapplication/json (application/vnd.org.jfrog.artifactory.system.ImportSettings+json)
Produces: text/plain
Sample Usage:

POST /api/import/system
{
import-settings.json
}

Export System Settings Example

Description: Returned default Export Settings JSON.
Security: Requires a valid admin user
Usage: GET: /api/export/system
Producesapplication/json (application/vnd.org.jfrog.artifactory.system.ExportSettings+json)
Sample Usage:

GET /api/export/system
{
  "exportPath" : "/export/path",
  "includeMetadata" : true,
  "createArchive" : false,
  "bypassFiltering" : false,
  "verbose" : false,
  "failOnError" : true,
  "failIfEmpty" : true,
  "m2" : false,
  "incremental" : false,
  "excludeContent" : false
}

Export System

Description: Export full system to a server local directory.
Security: Requires a valid admin user
Usage: POST: /api/export/system
Consumes : application/json (application/vnd.org.jfrog.artifactory.system.ExportSettings+json)
Produces: text/plain
Sample Usage:

POST /api/export/system{ export-settings.json } 

ERROR RESPONSES

In case of an error, JFrog Container Registry will return an error response in JSON format. The response contains the HTTP status code and error message.

For example, a badly formatted API call would return the "404, File not found" response below:

{
  "errors" : [ {
    "status" : 404,
    "message" : "File not found."
  } ]
}


Sample input:

POST /api/security/apiKey
{
    "apiKey": "3OloposOtVFyCMrT+cXmCAScmVMPrSYXkWIjiyDCXsY="
}
PUT /api/storage/libs-release-local/ch/qos/logback/logback-classic/0.9.9?properties=os=win,linux;qa=done&recursive=1


When parameters can have multiple values, you can separate the items in one of the following ways:

  • Use a semicolon - ; (recommended)
  • Use the encoding for the pipe ("|") character - %7C
    Alternatively, you may configure your NGINX to encode URLs so that if an unencoded pipe is used in the URL, NGINX will encode it to %7C. We recommend that you verify that this configuration does not break any other systems served by NGINX