The Swivle REST API allows you to customize and integrate applications with Swivle. Some examples of what you can do with the API:

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

The main purpose of the Swivle API is to allow your own customizations to talk with the back-end of Swivle.

Swivle API Reference

A detailed API reference is available at:

There you can find technical details on everything that you can do with the Swivle API.

Connecting to the API

Playing around and testing the API

If you just want to test the API and try some of the calls, this can be done directly from the Swivle API Reference page. First click the Authorize  button on that page and enter your API key (found in the Management Console):

On the reference page we automatically exchange the API key for an authToken and pass it 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.

Once you are authorized, you can 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. The tools provided by Swagger allow you to automatically generate an API client for almost any programming language and then use that to connect to the Swivle API.

Using curl

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

API Subscription

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

Regions

The Swivle API is available in 4 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:

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 receive API key. This API key allows full access to all the assets and other data in your tenant.

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

Your API key is like a password. Make sure you handle it with care. Keep it private, do not publish it anywhere public like 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, since 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 a 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 (max 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.

Did this answer your question?