General

Access and Versioning

The Bintray REST API is versioned. The latest version of the API will always be available at:

A sepcific version can be accessed at:

Authentication

The Bintray REST API requires an applicative API key. An API key can be obtained from the user profile page. Authentication is achieved using HTTP Basic Authentication with the user’s name as username and the API key as the password. Authenticated REST calls should only be used via HTTPs.

Limits

API queries are limited according to the following rules: Limits only apply to resources that do not belong to a user or to the organization the user is part of. The current limit per-user is 300 queries a day. Limits are returned in the X-RateLimit headers. For example:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 257

Pagination

Results may be subject to pagination, where only 50 the results of a single page are returned by each query. The current page size is 50 results per page. In this case the start_pos query parameter may be specified. The X-RangeLimit headers may be included in the response to indicate what results are being viewed.

GET /../../..&start_pos=250
X-RangeLimit-Total: 20000
X-RangeLimit-StartPos: 250
X-RangeLimit-EndPos: 299

Repositories

Get Repositories

GET /repos/:subject

Get a list of repos writeable by subject (personal or organizational)
This resource does not require authentication

Status: 200 OK
[{
"name": "repo",
"owner": "subject"
}]

Get Repository

GET /repos/:subject/:repo

Get general information about a repository of the specified user

Status: 200 OK
{
"name": "repo",
"owner": "user",
"desc": "This repo...",
"labels": ["java", "maven"],
"created": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)",
"package_count": 87
}
GET /search/repos?name=:name&desc=:desc

Search for a repository. At least one of the name and desc search fields need to be specified. Returns an array of results, where elements are similar to the result of getting a single repository.

PUT /repository/:subject/:repo/links/:source_subject/:source_repo/:source_package

Link the package source_package into the repo repository.
Caller must be an owner of the repository or an admin of the organization owning the repository.

Status: 201 Created
{
"message": "success"
}
DELETE /repository/:subject/:repo/links/:source_subject/:source_repo/:source_package

Unlink the package source_package from the repo repository.
Caller must be an owner of the repository or an admin of the organization owning the repository.

Status: 200 OK
{
"message":"success"
}

Packages

Get Packages

GET /repos/:subject/:repo/packages[?start_pos=122][&start_name=prefix]

Get a list of packages in the specified repository, optionally specify a starting position and/or a name prefix filter This resource can be consumed by both authenticated and anonymous clients. For anonymous clients it will return no more than 100 results

Status: 200 OK
[{
  "name": "package1",
  "linked": false
}]

Get Package

GET /packages/:subject/:repo/:package

Get general information about a specified package
This resource does not require authentication

Status: 200 OK
{
"name": "my-package",
"repo": "repo",
"owner": "user",
"desc": "This package...",
"labels": ["persistence", "database"],
"attribute_names": ["licenses", "vcs", "github", ...],
"rating": 8,
"rating_count": 8,
"followers_count": 82,
"created": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)",
"website_url":"",
"issue_tracker_url":"https://github.com/bintray/bintray-client-java/issues",
"github_repo":"" (publishers only),
"github_release_notes":"" (publishers only),
"public_download_numbers":false (publishers only),
"linked_to_repos":[],
"versions": ["0.9", "1.0", "1.0.1", ...],
"latest_version": "1.2.5",
"updated": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)",
"vcs_url": "https://github.com/bintray/bintray-client-java.git"
}

Create Package

POST /packages/:subject/:repo

Creates a new package in the specified repo (user has to be an owner of the repo)
licenses value needs to come from a predefined list [1]

{
"name": "my-package",
"desc": "This package...",
"labels": ["persistence", "database"],
"licenses": ["Apache-2.0", "GPL-3.0"],
"vcs_url": "https://github.com/bintray/bintray-client-java.git"
}
Status: 201 OK
{Package get JSON response}

Delete Package

DELETE /packages/:subject/:repo/:package

Delete the specified package

Status: 200 OK
{
"message":"success"
}

Update Package

PATCH /packages/:subject/:repo/:package

Update the information of the specified package

Status: 200 OK
{
"desc": "This package...",
"labels": ["persistence", "database"],
"licenses": ["Apache-2.0", "GPL-3.0"],
"vcs_url": "https://github.com/bintray/bintray-client-java.git"
}
GET /search/packages/?name=:name&desc=:desc[&subject=:subject&repo=:repo]
GET /search/users?name=:name

Search for a package. At least one of the name and desc search fields need to be specified. May take an optional single subject name and if specified, and optional (exact) repo name. Returns an array of results, where elements are similar to the result of getting a single package.

Versions

Get Version

GET /packages/:subject/:repo/:package/versions/:version
GET /packages/:subject/:repo/:package/versions/_latest

Get general information about a specified version, or query for the latest version

Status: 200 OK
{
"name": "1.1.5",
"desc": "This version...",
"package": "my-package",
"repo": "repo",
"owner": "user",
"lables": ["OSS", "org-name", ...],
"attribute_names": ["licenses", "vcs", "github", ...],
"created": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)",
"updated": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)",
"released": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)",
"ordinal": 5
}

Create Version

POST /packages/:subject/:repo/:package/versions

Creates a new version in the specified package (user has to be owner of the package)

{
"name": "1.1.5",
"released": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)" (optional)
"desc": "This version..."
"vcs_tag": "1.1.5" (optional)
}
Status: 201 CREATED
{Version get JSON response}

Delete Version

DELETE /packages/:subject/:repo/:package/versions/:version

Delete the specified version Published versions may be deleted within 30 days from their publish date.

Status: 200 OK
{
"message":"success"
}

Update version

PATCH /packages/:subject/:repo/:package/versions/:version

Update the information of the specified version

Status: 200 OK
{
"desc": "This package...",
"vcs_tag": "1.1.5"
}

Attributes

Get attributes

GET /packages/:subject/:repo/:package/attributes[?names=:att1,:att2]
GET /packages/:subject/:repo/:package/versions/:version/attributes[?names=:att1,:att2]

Get attributes associated with the specified package or version. If no attribute names are specified, return all attributes.

Status: 200 OK
[
{"name": "att1", "values" : ["val1"], "type": "string"},
{"name": "att2", "values" : [1, 2.2, 4], "type": "number"},
{"name": "att3", "values" : ["2011-07-14T19:43:37+0100", "2011-07-14T19:43:37+0100", "1994-11-05T13:15:30Z"], "type": "date"}
]

Set attributes

POST /packages/:subject/:repo/:package/attributes
POST /packages/:subject/:repo/:package/versions/:version/attributes

Associate attributes with the specified package or version, overriding all previous attributes. Attributes may have a null value. Optionally, specify an attribute type. Otherwise, type will be inferred from the attribute’s value. If a type cannot be inferred, string type will be used. Non-homogeneous arrays are not accepted. Attribute types can be one of the following: string, date, number, boolean, version version currently behaves like string. This will change with future Bintray versions.

[
{"name": "att1", "values" : ["val1"], "type": "string"}, //string
{"name": "att2", "values" : [1, 2.2, 4]}, //number
{"name": "att3", "values" : ["2011-07-14T19:43:37+0100", "2011-07-14T19:43:37+0100", "1994-11-05T13:15:30Z"], "type": "date"}, //date
{"name": "att4", "values" : [1.1, "elephant", 3.1]}, //BAD REQUEST
]
Status: 200 OK

Update attributes

PATCH /packages/:subject/:repo/:package/attributes
PATCH /packages/:subject/:repo/:package/versions/:version/attributes

Update attributes associated with the specified package or version. Attributes may have a null value. Optionally, specify an attribute type. Otherwise, type will be inferred from the attribute’s value. If a type cannot be inferred, string type will be used. Non-homogeneous arrays are not accepted. Attribute types can be one of the following: string, date, number, boolean, version version currently behaves like string. This will change with future Bintray versions.

[
{"name": "att1", "values" : ["val1"], "type": "string"}, //string
{"name": "att2", "values" : [1, 2.2, 4]}, //number
{"name": "att3", "values" : ["2011-07-14T19:43:37+0100", "2011-07-14T19:43:37+0100", "1994-11-05T13:15:30Z"], "type": "date"},
{"name": "att4", "values" : [1.1, "elephant", 3.1]} //string
]
Status: 200 OK

Delete attributes

DELETE /packages/:subject/:repo/:package/attributes[?names=:att1,:att2]
DELETE /packages/:subject/:repo/:package/versions/:version/attributes[?names=:att1,:att2]

Delete attributes associated with the specified repo, package or version. If no attribute names are specified, delete all attributes

Status: 200 OK
{
"message":"success"
}
POST /search/attributes/:subject/:repo
POST /search/attributes/:subject/:repo/:package/versions

Search for packages/versions inside a given repository matching a set of attributes. The AND opartor will be used when using multiple query clauses, for example attribute A equals X and attribute B is greater than Z When an array value is used, if the existing attribute value is a scalar match against one of the array values; if the existing attribute value is an array check that the existing array contains the query array.

Returns an array of results, where elements are similar to the result of getting a single package or a single version, accordingly.

[
{"att1" : ["val1", "val2"]}, //att1 value is either val1 or val2 (att1 is a scalar)
{"att2": "[1,3]"}, //att2 value is equal to or greater than 1 and equal to or smaller than 3
{"att3": "[,3]"}, //att3 value is equals to or smaller than 3
{"att4": "[,3["}, //att3 value is smaller than 3
{"att5": "]2011-07-14T19:43:37+0100,]"}, //att5 value  is after 2011-07-14T19:43:37+0100 (dates are defined in ISO8601 format)
]
Status: 200 OK
[
{
package or version object
},
{
package or version object
}
]

Users & Organizations

Get User

GET /users/:user

Get general information about a specified repository owner

Status: 200 OK
{
"name": "user",
"full_name": "First M. Last",
"gravatar_id": "whatever",
"repos": ["repo1", "repo2"],
"organizations": ["org1", "org2"],
"followers_count": 82,
"registered": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)",
"quota_used_bytes": 55720
}

Get Followers

GET /users/:user/followers[?start_pos=50]

Get followers of the specified repository owner

Status: 200 OK
[
{"name": "user1"},
{"name": "user2"}
]
GET /search/users?name=:name

Search for a user. Returns an array of results, where elements are similar to the result of getting a single user.

Content Uploading & Publishing

Upload Content

PUT /content/:subject/:repo/:package/:version/:file_path[&publish=0/1]

or:

X-Bintray-Package: :package
X-Bintray-Version: :version
PUT /content/:subject/:repo/:file_path[&publish=0/1]

or:

PUT /content/:subject/:repo/:file_path;bt_package=:package;bt_version=:version[&publish=0/1]

Upload content to the specified repository path, with package and version information (both required).
Package and version can be specified in one of the following ways:

  1. On the request path

  2. As request headers

  3. As matrix parameters

Optionally publishing the uploaded artifact(s) as part of uploading (off by default). Additional content can be uploaded to a published version within 5 days from its publish date.

Status: 201 Created
{
"message":"success"
}

Publish/Discard Uploaded Content

POST /content/:subject/:repo/:package/:version/publish

Publish all unpublished content for a user’s package version. Returns the number of published files. Optionally, pass in a "discard" flag to discard any unpublished content, instead of publishing.

{"discard" : true}
Status: 200 OK
{
"files": 39
}

Maven Upload

PUT /maven/:subject/:repo/:package/:file_path[&publish=0/1]

Upload Maven artifacts to the specified repository path, with package information (required). Version information is resolved from the path, which is expected to follow the Maven layout. Optional direct publishing (off by default).

Status: 201 Created
{
"message":"success"
}

File Searches

File Search by Name

GET /search/file?name=:name[&repo=:repo]

Search for a file by its name. name can take the * and ? wildcard characters. May take an optional (exact) repo name to search in.

Status: 200 OK
{
"name": "nutcracker-1.1-sources.jar",
"path": "org/jfrog/powerutils/nutcracker/1.1/nutcracker-1.1-sources.jar",
"package": "jfrog-power-utils",
"version": "1.1",
"repo": "jfrog-jars",
"owner": "jfrog",
"created": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)"
}

File Search by Checksum

GET /search/file?sha1=:sha1[&repo=:repo]

Search for a file by its sha1 checksum. May take an optional repo name to search in.

Status: 200 OK
{
"name": "nutcracker-1.1-sources.jar",
"path": "org/jfrog/powerutils/nutcracker/1.1/nutcracker-1.1-sources.jar",
"package": "jfrog-power-utils",
"version": "1.1",
"repo": "jfrog-jars",
"owner": "jfrog",
"created": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)"
}

Signing

GPG Sign a Version

POST /gpg/:subject/:repo/:package/versions/:version
{
"passphrase": "passphrase"
}

GPG sign all files associated with the specified version.
This operation requires enabling GPG signing on the targeted repo.
A GPG key-pair can be configured for reposiotry owners (individuals or organizations).
In case the private key in use requires a passphrase, you may also supply one by a JSON file

Status: 200 OK
{
"message":"success"
}

GPG Sign a File

POST /gpg/:subject/:repo/:file_path
{
"passphrase": "passphrase"
}

GPG sign the specified repository file.
This operation requires enabling GPG signing on the targeted repo.
A GPG key-pair can be configured for reposiotry owners (individuals or organizations).
In case the private key in use requires a passphrase, you may also supply one using the passphrase query parameter.

Status: 200 OK
{
"message":"success"
}

Logs

List package download log files

GET /packages/:subject/:repo/:package/logs

Retrive a list of available download log files for a package

Status: 200 OK
[{
"name": "downloads-05-11-2013.log.gz",
"size": 209,
"update": "2013-11-05T12:55:00Z",
},
…
]

Download package download log file

GET /packages/:subject/:repo/:package/logs/:log_name

Download the package download log file specified by log_name

Status: 200 OK

Webhooks

Get Webhooks

GET /webhooks/:subject[/:repo]

Get all the webhooks registered for the specified subject, optionally for a specific repository.

failure_count is the number of times a callback has failed. A callback will be auto-deactivated after 7 subsequent failures. A successful callback resets the count.

Status: 200 OK
[
{
"package": "my-package",
"url": "http://callbacks.myci.org/%r-%p-build",
"failure_count": "3",
},
…
]

Register a Webhook

POST /webhooks/:subject/:repo/:package

Register a webhook for receiving notifications on a new package release. By default a user can register up to 10 webhook callbacks. The callback URL may contain the %r and %p tokens for repo and package name, respectively. method is the callback request method: can be in post, put or get. If not specified, post is used.

{
"url": "http://callbacks.myci.org/%r-%p-build",
"method": "post"
}
Status: 201 CREATED
X-Bintray-WebHookLimit-Limit: 10
X-Bintray-WebHookLimit-Remaining: 2

Test a Webhook

POST /webhooks/:subject/:repo/:package/:version

Test a webhook callback for the specified package release. A webhook post request is authenticated with a authentication header that is the HMAC-MD5 of the registering subject’s API key seeded with package name, base64-encoded UTF-8 string.

{
"url": "http://callbacks.myci.org/%r-%p-build",
}
Status: 200 OK
"X-Bintray-WebHook-Hmac": "HMAC-MD5 of the API key, seeded with the package name"
{
"package": "my-package",
"version": "1.2.1",
"released": "ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)",
"release_notes": "This is a test" (TBD)
}

Delete a Webhook

DELETE /webhooks/:subject/:repo/:package

Delete a webhook associated with the specified package.

Status: 200 OK
{
"message":"success"
}

Content Sync

Sync version artifacts to Maven Central

POST /maven_central_sync/:subject/:repo/:package/versions/:version
{
"username": "userToken", // Sonatype OSS user token
"password": "passwordToken", // Sonatype OSS user password
"close": "1" // Optional
}

Sync version files to a oss.sonatype.org staging repository to publish these files to Maven Central.
By default the staging repository is closed and artifacts are released to Maven Central. You can optionally turn this behaviour off and release the version manually. This is achived by passing 0 in the close field of the JSON passed to the call.

Status: 200 OK
{
"status": "Successfully synced and closed repo.",
"messages": ["Sync finished successfully."]
}

© 2014 JFrog Ltd.


1. Available licenses: AFL-3.0, AGPL-V3, APL-1.0, Apache-1.0, Apache-1.1, APSL-2.0, Artistic-License-2.0, Attribution, BSL-1.0, CA-TOSL-1.1, CPAL-1.0, CPOL-1.02, CUAOFFICE-1.0, Day-Addendum, EUDATAGRID, Historical, IBMPL-1.0, IPAFont-1.0, ISC, Lucent-1.02, MirOS, MS-PL, MS-RL, MIT, BSD, GPL-2.0, JTidy, CPL-1.0, JA-SIG, JSON, Motosoto-0.9.1, ECL2, Eiffel-2.0, Entessa-1.0, EUPL-1.1, Fair, Frameworx-1.0, GPL-2.0+CE, Multics, NASA-1.3, NTP, NAUMEN, Nethack, Nokia-1.0a, NOSL-3.0, OCLC-2.0, Openfont-1.1, Opengroup, OSL-3.0, PHP-3.0, PostgreSQL, Public Domain - SUN, PythonPL, PythonSoftFoundation, QTPL-1.0, Real-1.0, RPL-1.5, RicohPL, SimPL-2.0, Sleepycat, SUNPublic-1.0, Sybase-1.0, UoI-NCSA, IU-Extreme-1.1.1, VovidaPL-1.0, wxWindows, Xnet, ZPL-2.0, ZLIB, Codehaus, TMate, WTFPL, MPL-2.0, Public Domain, Eclipse-1.0, Bouncy-Castle, Apache-2.0, BSD Simplified, BSD New, LGPL-3.0, GPL-3.0, CDDL-1.0, HSQLDB, Day, Mozilla-1.1, LGPL-2.1, W3C, Go