The Swivle API

The Swivle REST API allows you to customize and integrate applications with Swivle.

Jouke Jongsma avatar
Written by Jouke Jongsma
Updated over a week ago

Dear Swivle user, we are in the process of migrating the Swivle documentation to the main WoodWing Help Center.

The article that you are reading now will therefore not be updated anymore.

For the latest information about this topic, please visit the new version of this article.

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

  • 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.

API subscription

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

Swivle API Reference

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

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. 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 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 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.

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, 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 (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?