The Swivle REST API

With the Swivle REST API you can customize and integrate applications with Swivle. Some examples of what you can do with the API are:

• Search for files
• Download files, previews, or other derived formats
• Upload files
• Change metadata
• Create folders and Collections
• Create Shared links
• and much more...

The main purpose of the Swivle API is to have your own customizations connect to the back-end of Swivle.

API subscription

To make use of the API, a Swivle API subscription or a subscription plan that includes the API is needed. You can buy your API subscription on the Subscriptions page in the Management Console.

API reference

A detailed API reference is available at https://api.swivle.com.

Testing the API

Testing the API to try some of the calls can be done directly from the Swivle API Reference page.

Step 1. Click the Authorize button and enter your API key (found on the API page of the Management Console).

The API key is automatically exchanged for an authToken and passed as a header (you can see this when you try out a request). Normally you would have to do that manually. We explain how to do this later in the article.

Step 2. Once you are authorized, use the Try it out button to test each of the API calls.

Generating an API client for your language

The API is documented using the Swagger 2.0 OpenAPI Specification. With the tools provided by Swagger you can automatically generate an API client for almost any programming language and then use that to connect to the Swivle API.

Using curl

Because the API is REST-based it is also very easy to directly connect to it using tools such as curl. When you try out API calls in the Swivle API Reference, it automatically generates sample curl commands for you.

Regions

The Swivle API is available in various regions. Which region you should connect to depends on where you signed up from.

You can find a link to the API endpoint for your region on the API page in the Management Console.

The following API endpoints are available:

• https://api-eu-west-1.swivle.com (Ireland)
• https://api-eu-west-2.swivle.com (London, UK)
• https://api-us-east-1.swivle.com (North Virginia, US)
• https://api-ap-southeast-1.swivle.com (Singapore)
• https://api-ap-southeast-2.swivle.com (Sydney, Australia)

Authentication

To be able to use the API, you first need to authenticate. This works by exchanging your API key for an authentication token. That token then needs to be included as a header in all the subsequent API calls that you make.

Note: Your API key and your auth token are very different. The first is like a permanent password.

API key

If you have a Swivle API subscription, you will have an API key. This API key allows full access to all the files and data in your tenant.

You can find your API key on the API page in the Management Console.

Important: Your API key is like a password. Make sure you handle it with care. Keep it private, do not publish it anywhere public such as on a web page and do not commit it to a source-control system. Because your API key must remain private, it can only be used for server-to-server integrations. Do not use it in client-side browser code, because that would expose your API key.

In case your API key is exposed, you can generate a new API key on the API page in the Management Console. When you generate that new key, the old key can no longer be used to obtain auth-tokens. However, already issued auth-tokens will remain valid until they expire (maximum of 30 minutes).

Auth-token

Use the following call to exchange your API key for an auth-token:

POST <api-endpoint>/auth/api-key-login
{
   "apiKey": "...your-api-key..."
}

This will return:

{
   "authToken": "your.auth.token valid for 30 minutes",
   "expires": "2018-04-01T18:25:43.511Z"
}

Next, you need to pass the auth-token as Authorization header in subsequent API calls:

GET <api-endpoint>/api/asset/search?q=*:*
Authorization: Bearer your.auth.token

Each auth-token is only valid for a limited time, typically 30 minutes. After that time you will receive a 401 response when making any API calls. Make sure you request a new auth-token using your API key at that point or even better: before your auth-token expires.