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

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
Column
width75%

Overview

Artifactory exposes its REST API through an auto-generated WADL file (courtesy of the Jersey REST framework).

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

The WADL file is available at the following URL:
http://server:port/artifactory/api/application.wadl

Usage

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

Tip
titleUsing and Configuring cURL

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

Authentication

Artifactory's REST API supports three 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.
Note
titleArtifactory version

 To use your API key for Basic Authentication, it must be generated using Artifactory 4.4.3 or later. If generated on a previous version, you must regenerate your API key and use the new key as a password for basic authentication.

Using JFrog CLI

JFrog CLI is a compact and smart client that provides a simple interface to automate access to Artifactory. 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

Newtablink
TextJFrog CLI User Guide
URLCLI:Welcome to JFrog https://www.jfrog.com/confluence/display/CLI/Welcome+to+JFrog+CLI
.

Example - Deploying 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 Artifactory 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 Artifactory 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:

Code Block
titleUsing cURL with the REST API
curl -u myUser:myP455w0rd! -X PUT "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt
Code Block
languagetext
titleUsing JFrog CLI
jfrog rt u file.txt my-repository/my/new/artifact/directory/ --user=myUser --password=myP455w0rd!

 

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

Code Block
languagetext
titleUsing cURL with the REST API
curl -u myUser:ABcdEF -X PUT "http://localhost:8081/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt
Code Block
languagetext
titleUsing JFrog CLI
jfrog rt u file.txt my-repository/my/new/artifact/directory/ --apiKey=ABcdEF

 

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

Code Block
languagetext
titleUsing cURL with the REST API
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

 

 

REST Resources

The sections below provide a comprehensive listing of the REST resources exposed by Artifactory.

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

Note

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

 


BUILDS

All Builds

Description: Provides information on all builds
Since: 2.2.0
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/build
Produces: application/vnd.org.jfrog.build.Builds+json
Sample Output:

Code Block
GET /api/build
{
    "uri": "http://localhost:8080/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
Since: 2.2.0
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/build/{buildName}
Produces: application/vnd.org.jfrog.build.BuildsByName+json
Sample Output:

Code Block
GET /api/build/my-build
{
    "uri": "http://localhost:8080/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 (can be anonymous)
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/vnd.org.jfrog.build.BuildsByName+json
Example: curl -X PUT "http://localhost:8080/artifactory/api/build" -H "Content-Type: application/json" --upload-file build.json
Sample input: 

Expand
titleClick to view sample build.json
Code Block
{
  "version" : "1.0.1",
  "name" : "Maven2-3",
  "number" : "9",
  "type" : "MAVEN",
  "buildAgent" : {
    "name" : "Maven",
    "version" : "3.0.5"
  },
  "agent" : {
    "name" : "Jenkins",
    "version" : "1.565.2"
  },
  "started" : "2015-03-20T11:01:38.445+0200",
  "durationMillis" : 8926,
  "artifactoryPrincipal" : "admin",
  "url" : "http://localhost:8080/job/Maven2-3/9/",
  "vcsRevision" : "83049487ecc61bef3dce798838e7a9457e174a5a",
  "vcsUrl" : "https://github.com/aseftel/project-examples",
  "licenseControl" : {
    "runChecks" : false,
    "includePublishedArtifacts" : false,
    "autoDiscover" : true,
    "scopesList" : "",
    "licenseViolationsRecipientsList" : ""
  },
  "buildRetention" : {
    "count" : -1,
    "deleteBuildArtifacts" : true,
    "buildNumbersNotToBeDiscarded" : [ ]
  },
  "modules" : [ {
    "properties" : {
      "project.build.sourceEncoding" : "UTF-8"
    },
    "id" : "org.jfrog.test:multi:2.19-SNAPSHOT",
    "artifacts" : [ {
      "type" : "pom",
      "sha1" : "045b66ebbf8504002b626f592d087612aca36582",
      "md5" : "c25542a353dab1089cd186465dc47a68",
      "name" : "multi-2.19-SNAPSHOT.pom"
    } ]
  }, {
    "properties" : {
      "project.build.sourceEncoding" : "UTF-8"
    },
    "id" : "org.jfrog.test:multi1:2.19-SNAPSHOT",
    "artifacts" : [ {
      "type" : "jar",
      "sha1" : "f4c5c9cb3091011ec2a895b3dedd7f10d847361c",
      "md5" : "d1fd850a3582efba41092c624e0b46b8",
      "name" : "multi1-2.19-SNAPSHOT.jar"
    }, {
      "type" : "pom",
      "sha1" : "2ddbf9824676f548d637726d3bcbb494ba823090",
      "md5" : "a64aa7f305f63a85e63a0155ff0fb404",
      "name" : "multi1-2.19-SNAPSHOT.pom"
    },
   
   ...
 
   {
      "type" : "jar",
      "sha1" : "6fdd143a44cea3a2636660c5c266c95c27e50abc",
      "md5" : "12a1e438f4bef8c4b740fe848a1704a4",
      "id" : "org.slf4j:slf4j-simple:1.4.3",
      "scopes" : [ "compile" ]
    }, {
      "type" : "jar",
      "sha1" : "496e91f7df8a0417e00cecdba840cdf0e5f2472c",
      "md5" : "76a412a37c9d18659d2dacccdb1c24ff",
      "id" : "org.jenkins-ci.lib:dry-run-lib:0.1",
      "scopes" : [ "compile" ]
    } ]
  }, {
    "properties" : {
      "daversion" : "2.19-SNAPSHOT",
      "project.build.sourceEncoding" : "UTF-8"
    },
    "id" : "org.jfrog.test:multi2:2.19-SNAPSHOT",
    "artifacts" : [ {
      "type" : "txt",
      "name" : "multi2-2.19-SNAPSHOT.txt"
    }, {
      "type" : "java-source-jar",
      "sha1" : "49108b0c7db5fdb4efe3c29a5a9f54e806aecb62",
      "md5" : "0e2c5473cf2a9b694afb4a2e8da34b53",
      "name" : "multi2-2.19-SNAPSHOT-sources.jar"
    }, 
 
    ...
 
    {
      "type" : "jar",
      "sha1" : "476e89d290ae36dabb38ff22f75f264ae019d542",
      "md5" : "fa9b3df58ac040fffcff9310f261be80",
      "name" : "multi2-2.19-SNAPSHOT.jar"
    }, {
      "type" : "pom",
      "sha1" : "b719b90364e5ae38cda358072f61f821bdae5d5d",
      "md5" : "8d5060005235d75907baca4490cf60bf",
      "name" : "multi2-2.19-SNAPSHOT.pom"
    } ],
    "dependencies" : [ {
      "type" : "jar",
      "sha1" : "19d4e90b43059058f6e056f794f0ea4030d60b86",
      "md5" : "dcd95bcb84b09897b2b66d4684c040da",
      "id" : "xpp3:xpp3_min:1.1.4c",
      "scopes" : [ "provided" ]
    }, {
      "type" : "jar",
      "sha1" : "e2d866af5518e81282838301b49a1bd2452619d3",
      "md5" : "e9e4b59c69305ba3698dd61c5dfc4fc8",
      "id" : "org.jvnet.hudson.plugins:perforce:1.3.7",
      "scopes" : [ "compile" ]
    }, 
 
   ...
 
   {
      "type" : "jar",
      "sha1" : "6fdd143a44cea3a2636660c5c266c95c27e50abc",
      "md5" : "12a1e438f4bef8c4b740fe848a1704a4",
      "id" : "org.slf4j:slf4j-simple:1.4.3",
      "scopes" : [ "compile" ]
    }, {
      "type" : "jar",
      "sha1" : "496e91f7df8a0417e00cecdba840cdf0e5f2472c",
      "md5" : "76a412a37c9d18659d2dacccdb1c24ff",
      "id" : "org.jenkins-ci.lib:dry-run-lib:0.1",
      "scopes" : [ "compile" ]
    } ]
  }, {
    "properties" : {
      "project.build.sourceEncoding" : "UTF-8"
    },
    "id" : "org.jfrog.test:multi3:2.19-SNAPSHOT",
    "artifacts" : [ {
      "type" : "java-source-jar",
      "sha1" : "3cd104785167ac37ef999431f308ffef10810348",
      "md5" : "c683276f8dda97078ae8eb5e26bb3ee5",
      "name" : "multi3-2.19-SNAPSHOT-sources.jar"
    }, {
      "type" : "war",
      "sha1" : "34aeebeb805b23922d9d05507404533518cf81e4",
      "md5" : "55af06a2175cfb23cc6dc3931475b57c",
      "name" : "multi3-2.19-SNAPSHOT.war"
    }, 
 
    ...
 
   {
      "type" : "jar",
      "sha1" : "496e91f7df8a0417e00cecdba840cdf0e5f2472c",
      "md5" : "76a412a37c9d18659d2dacccdb1c24ff",
      "id" : "org.jenkins-ci.lib:dry-run-lib:0.1",
      "scopes" : [ "compile" ]
    }, {
      "type" : "jar",
      "sha1" : "7e9978fdb754bce5fcd5161133e7734ecb683036",
      "md5" : "7df83e09e41d742cc5fb20d16b80729c",
      "id" : "hsqldb:hsqldb:1.8.0.10",
      "scopes" : [ "runtime" ]
    } ]
  } ],
  "governance" : {
    "blackDuckProperties" : {
      "runChecks" : false,
      "includePublishedArtifacts" : false,
      "autoCreateMissingComponentRequests" : false,
      "autoDiscardStaleComponentRequests" : false
    }
  }

 


 

Build Info

Description: Build Info
Since: 2.2.0
Security: Requires a privileged user with deploy permissions (can be anonymous)
Usage: GET /api/build/{buildName}/{buildNumber}
Produces: application/vnd.org.jfrog.build.BuildInfo+json
Sample Output:

Code Block
GET /api/build/my-build/51
{
"uri": "http://localhost:8080/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).
Since: 2.6.6
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/build/{buildName}/{buildNumber}?diff={OlderbuildNumber}
Produces: application/vnd.org.jfrog.build.BuildsDiff+json
Sample Output:

Code Block
GET /api/build/my-build/51?diff=50
{
    "artifacts": {
        "updated": [],
        "unchanged": [],
        "removed": [],
        "new": []
    }, "dependencies": {
        "updated": [],
        "unchanged": [],
        "removed": [],
        "new": []
    }, "properties": {
        "updated": [],
        "unchanged": [],
        "removed": [],
        "new": []
    }
}
Column
Info
iconfalse
titlePage contents

Table of Contents
maxLevel4
minLevel2
indent20px

Info
iconfalse
titleRead More

Children Display

...

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.
Since:
 3.1.0
Security:
 Requires read privileges
Usage:
 GET /api/storage/{repoKey}/{item-path}?stats
Produces: application/vnd.org.jfrog.storage.StatsInfo+json
Sample Output:

...