Fetching data

The SyncSketch API is based on the powerful “Tastypie” REST module for django. Besides expsoing the standard REST endpoints, you can use the Django querying language to fetch just the data you want.

Please refer to the Tastypie documentation for a more in depth look.

Note

If you are logged into SyncSketch Pro, your API Info will automatically appear in the documentation. Nobody else will see your info!

Searching by attribute

Tastypie uses the django search paradigm and allows for most of the filtering mechanisms that django provides which include in, contains, startswith, range, etc... You can find more information in the Django Documentation

A simple example would be to query a list of projects or reviews by name. This can be accomplished using the following API call:

https://www.syncsketch.com/api/v1/project/?name=PROJECT_NAME&username=YOUR_USERNAME&api_key=YOUR_APIKEY

This call searches for the projects with exactly that name. If you want to have all projects that start with “class” then you can use:

https://www.syncsketch.com/api/v1/project/?name__startswith=class&username=YOUR_USERNAME&api_key=YOUR_APIKEY

As mentioned before, you can use various filtering methods which are all native to Django like in, contains, isnotnull, etc.

Creating Records

When interacting with the API, one of the main goals is to create Projects, Reviews and upload videos or images for a review. Let’s have a look how that is done.

Project

curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name":"api test project","description":"test"}' "https://www.syncsketch.com/api/v1/project/?username=YOUR_USERNAME&api_key=YOUR_APIKEY"

Review

curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name":"api test review","description":"test","project":"/api/v1/project/44/"}' "https://www.syncsketch.com/api/v1/review/?username=?username=YOUR_USERNAME&api_key=YOUR_APIKEY"

When creating a review please remember to add also inlcude the PROJECT ID for the review

Updating Records

To update records you can use the same API endpoints and just use another header type e.g PUT, DELETE, PATCH, etc...

To change the description of a review you can easily do something like this:

curl --dump-header - -H "Content-Type: application/json" -X PATCH --data '{"description":"updated the description through the API"}' "https://www.syncsketch.com/api/v1/review/REVIEW_ID/?username=YOUR_USERNAME&api_key=YOUR_APIKEY"

This makes it easy to update the SyncSketch records to stay in sync with your database.

Uploading Media

SyncSketch has currently two methods for uploading media to your account - a simple and a more advanced version. The simple version does a lot of the heavy lifting for you by looking up the project and review by name. The API will create the project and review for you automatically if they don’t already exist. You can also pass in the users email who created the media item and set the projects public flag.

curl -X POST -F "mediaFile=@$PATH_TO_YOUR_FILE" -F "$ARTISTEMAIL" -F "isPublicProject=1" -F "projectName=Test Project" -F "reviewName=Test Review" -F "accountId=$ACCOUNT_ID" "https://www.syncsketch.com/api/v1/item/uploader/?username=YOUR_USERNAME&api_key=YOUR_APIKEY"

Let’s have a closer look at the parameters.

  • -X POST - Tell the API it’s a POST request
  • -F mediaFile - Path to your file. Param name mediaFile is important and the @ for curl to work!
  • -F email - Email of the user who created the file e.g the artist email
  • -F isPublicProject - Should this project be public or private. Public means anyone with the link to the review can see it. Default = ‘’
  • -F projectName - Name of the project
  • -F reviewName - Name of the review
  • -F accountId - Id of the account

Note

The uploader can’t guess which account you want to upload to in case you are connected to multiple accounts. To find out the accounts you are connected with head over to Account API

Easy, no?

The more advanced version uploads the file directly to a review by using the review id. This means you have to create your review with the regular API methods or use an already existing review id.

curl -i -F reviewFile=@test.webm "https://www.syncsketch.com/items/uploadToReview/REVIEW_ID/?username=?username=YOUR_USERNAME&api_key=YOUR_APIKEY"

You can only upload data to a valid review that you have access to. SyncSketch will check your credentials and make sure that no one without the right permissions can access your review information.

Adding Users to a project

Adding users to a project is a little different. You can use a regular project endpoint and pass in a list of comma separated emails like so:

https://www.syncsketch.com/api/v1/project/PROJECT_ID/addUsers/?emails=COMMA_SEPARATED_LIST_OF_EMAILS&username=YOUR_USERNAME&api_key=YOUR_APIKEY

an example call would be:

https://www.syncsketch.com/api/v1/project/45/addUsers/?emails=test@test.com,test1@test.com&username....

If a user already has a SyncSketch account we will be notify him about the new project. In case the user has never used SyncSketch, we will send an email invitation with instructions to join and register with SyncSketch. Once he is registered the project will be automatically showing up in his list of projects.

EmailInvitation Sample email invitation for a user

Tips

To use the SyncSketch API you have to use GET parameters for username and api_key in every call. To make it easier you can create a wrapper function that appends the username and api_key at the end of each call.