API reference

The Cloudsmith REST (REpresentational State Transfer) API (Application Programming Interface) provides everything you love about Cloudsmith but in a programmatic machine-accessible RESTful format. We believe in providing a rich API to enable exciting and powerful integrations, hopefully in ways that we couldn't imagine - just like your favourite brick-like toys.

Versioning

The API is versioned to help reduce future compatibility issues if we need to change the API.

Authentication

Most resources provided by the API require some form of authentication, which identifies the client to the API in the context of a particular user. Other resources are accessible anonymously, so they don't need authentication (although they may provide expanded detail for authenticated users). You can use the following methods to authenticate:

API key authentication

The most straightforward way to authenticate against the API is by using your personal API key. You can find your API Key within your User Settings or you can request (or reset) it via the Users Token API Endpoint. Cloudsmith Entitlement Tokens cannot be used to authenticate to the Cloudsmith API. Entitlement Tokens are used to authenticate for package downloads only.

You can specify your API Key via the Authorization header when making requests (replacing key with your actual API Key):

curl -H "Authorization: token $key" https://api.cloudsmith.io/user/self/

Specifying an invalid API Key will result in an 401 Unauthorized status code, and the body will specify that an invalid token was received. Let's see it in action:

curl -i -H "Authorization: token foobar" -X OPTIONS https://api.cloudsmith.io/user/self/

HTTP/2 401
date: Thu, 09 Mar 2023 16:55:35 GMT
server: Cloudsmith MCP

{"detail": "Invalid token."}

Using Service Accounts

If your API key is given to someone else they will be able to access the API in its entirety as you. This should be viewed as a security risk and every effort should be taken to protect your API Key from disclosure. If you need to add read-only access, we suggest creating a lesser privileged service account and using that instead for scripts/automation.

Pagination

API requests that return more than one item may be paginated, which simply means the total number of items is split into logical pages, in the same way that a book is split into pages. Each page will have a certain number of items in it from one up to the page limit - empty datasets are never paginated.

When pagination is enabled, the following query string parameters are supported:

When pagination occurs, the following headers will be represent in API responses:

The Link header can contain the following rel values:

Let's see it in action

curl -i -H "Authorization: token $key" 'https://api.cloudsmith.io/package/example/repo/packages/?page=2&page_size=1'

HTTP/1.0 200 OK
Allow: GET, OPTIONS
Content-Type: application/json
Link: <https://api.cloudsmith.io/package/example/repo/packages/?page=1>; rel="first", <https://api.cloudsmith.io/package/example/repo/packages/?page=1>; rel="prev", <https://api.cloudsmith.io/package/example/repo/packages/?page=3>; rel="next", <https://api.cloudsmith.io/package/example/repo/packages/?page=3>; rel="last"
X-Pagination-Count: 3
X-Pagination-Page: 2
X-Pagination-PageTotal: 3
X-Pagination-PageSize: 1
Server: Cloudsmith MCP
Date: Sun, 29 Jan 2017 18:40:55 GMT

[snip]

Page Sizes / Remainders

If the page size is 100 and the dataset size is 400, then there will be four pages available for retrieval. If the dataset isn't cleanly divided by the page size, the remainder will be on the final page. For example, if the page size is 100 and the dataset size is 350 then the last (4th) page will have 50 items on it.

Updated 6 days ago