Intro

The python SDKs are simply a wrapper over the underlying RESTful API. Excluding uploading, all actions in Shade are RESTful calls. This includes operations like making/moving directories, updating dynamic views, exporting things to CSV, making drives and editing permissions.

API Key

API keys can be generated in the web or desktop app. The API key has the same permissions as the account it is generated on. This means the API key will have access to the same things that you do when logged in with that account on the UI. All calls (other than to public endpoints like /) require the API key to be sent as well, otherwise Shade will give a permission error.

To generate the API key

1. In the app click settings at the top left

2. Underneath "My account" select the option for API keys

3. Select the purple Generate new key

4. Give your key a name as a label and set an expiration if desired

5. Continue, then make sure to copy the API key shown in purple to a safe place it will not be shown again once the popup is closed

The API key is always provided in the Authorization header as Authorization: sk_...

Endpoint

All Shade API calls in scope of this document are made to

https://api.shade.inc

Authorization Header

Shade uses the Authorization header instead of an API key URL parameter. This means you should always have the following header (and additional headers if needed):

{
    "Authorization": "sk_<your key>"   
}

There is no need to put Authorization Bearer, just put the secret key directly there!

A simple example request

Let's do a request to list workspaces that our account has access to. This can be doing any client that sends HTTP requests.

I'll give this example using cURL in the command line, but tools like postman can also be used or tools like requests in python. Make sure to replace the sk_... with your actual key.

curl -H "Authorization: sk_..." https://api.shade.inc/workspaces

This gives back something that looks like this

[
  {
    "id":"019d8690-fa10-45f3-b10c-0b0af64674fc"
  },
  "name":"Acme Studios",
  "description":"",
  "domain":"demo",
  "thumbnail":"https://firebasestorage...."

Export a view as CSV (more complex)

Often people want to export the view they have as a CSV so they can use this in other tools. This is easy over the API with a few pieces of information

1. The drive id

2. The view id

Just replace those two attributes in the below call.

curl -H "Authorization: sk_..." "https://api.shade.inc/dynamic-views/<the view id>/exports/csv?drive_id=<the drive id>&os=Darwin&timezone=America/New_York"

This gives back something like this. In my case this view doesn't have tags, but any metadata you have in this view will appear here

File Name,Clip Directory
concert_broll_1.mp4,/Volumes/final_cut_happy/final cut.fcpbundle/2-5-25/Original Media
concert_broll_2.mov,/Volumes/final_cut_happy/final cut.fcpbundle/2-5-25/Original Media

Operations like this can also be done via our python SDK, but this is what the raw calls look like under the hood!