Skip to main content

Do you want to know how to use the ftrack API? You’re in the right place. Below, we run through setting up the ftrack API and putting it into action.

Very rarely are two creative pipelines the same—which is why we built the ftrack API. With the ftrack API, you can customize ftrack Studio to work the way you need it and deliver projects in sync with your unique studio workflows.

For example, say there’s a specific platform you’d love to integrate with ftrack Studio, but it’s not yet on ftrack’s integrations list. Or maybe you want to create something particular to your studio hiring process, like setting up a studio-specific start-up wizard for new starters. Or perhaps you’re just fed up with spending a lot of time on tasks that could be much more efficiently batch-automated. The ftrack Python API can help you achieve these things and much more.

If you’re interested in trying out the ftrack API, but you’re not sure where to start, then you’re in the right place. Below, you can follow our guide to getting started with the ftrack API and access some useful links to get you off the ground.

Before we dive in, check out how others are using and benefiting from customizing ftrack Studio and bringing the platform in line with their unique studio requirements. Head to the end of the blog to see a recent webinar about the ftrack API, too!

Customers benefiting from the ftrack API

Plarium Global

NetEase Games

Cubic Motion

A guide to getting started with the ftrack API

ftrack is primarily a web application with an intuitive, modern interface, which lets users interact with creative projects and their assets while in production. If you want to dig deeper and start automating processes or get creative with how you use your data, you’ll want to roll up your sleeves and dive into the power of the ftrack API.

Below, we’ll run through the steps to getting started with ftrack’s Python API. We’ll use Python in this example due to its ease of use and readability (both being reasons for Python being an industry-standard programming language).

If you get stuck at all, you can find plenty of additional support in the form of documentation and ftrack’s community support. Also, be sure to check out our recent ftrack API 2.0 update.

Here’s the best starting point for using the ftrack Python API: ftrack-python-api.readthedocs.io/en/stable

1. Install Python, if you haven’t already

If you don’t have Python installed, then your first step is to install it. There’s a good chance your system already includes Python, but if it doesn’t then you can get it from python.org. In this post, we’ll be using Python 3.8.

Once installed, verify you have Python working with:

$ python —version
python 3.8.9

2. Set up a virtual environment for experimentation (if you want to!)

One more nice-to-have tool when working with Python is a virtual environment, created using Python’s venv module. Virtual environments allow you to set up a sandbox where you can specify Python versions for use and install Python modules without polluting your system’s Python environment. You can create and “activate” a virtual environment with the following commands:

$ python3 -m venv /path/to/new/virtual/environment
$ cd /path/to/new/virtual/environment
$ source ./bin/activate

Please note that this is our suggestion/best practice approach to working with Python via virtual environments. Other options are available, but we’ll stick with this approach in this tutorial.

3. Install the ftrack API and iPython

Now we can install the ftrack API using PIP (the Python package installer). Here’s what to run:

$ pip install ftrack-python-api
[…some output omitted…]
Successfully installed ftrack-python-api-2.3.0

Another helpful module that’s especially useful when exploring new APIs is iPython. iPython is an enhanced interactive Python shell that helps you make the most of using Python interactively. The most applicable features include:

  • Comprehensive object introspection.
  • Input history, persistent across sessions.
  • Extensible tab completion, with support by default for completion of python variables and keywords, filenames, and function keywords.

Note that iPython is not required, but it’s really nice to have as you explore the API interactively. Install iPython with:

$ pip install ipython

Then, start an ipython shell with the following command:

% ipython
Python 3.8.9 (default, Oct 26 2021, 07:25:54)
Type 'copyright', 'credits' or 'license' for more information
IPython 8.0.0 -- An enhanced Interactive Python. Type '?' for help.
In [1]:

4. Get API authentication credentials

One more thing you’ll need is API authentication credentials. You can get API authentication credentials from your account page in ftrack Studio. To do so, head to your My Account page. You’ll see a “Personal API Key”, your “Username” (email), and the base URL for your ftrack instance from your browser’s address bar. Once you have these credentials, you can configure them by setting the following environment variables for your shell (bash, zsh):

Alternatively, you can enter your credential in code when you create your Session object (which you’ll use to interact with the API). Here’s how that looks:

In [1]: import ftrack_api
In [2]: session = ftrack_api.Session(
   ...: server_url="https://mycompany.ftrackapp.com",
   ...: api_key="7545384e-a653-11e1-a82c-f22c11dd25eq",
   ...: api_user="[email protected]",
   ...: )

Or, if you’ve configured your credentials using environment variables, then the commands would be:

In [1]: import ftrack_api
In [2]: session = ftrack_api.Session()

Notice in the examples above that we first imported the ftrack API package. We then configured and instantiated a Session object. If both of these commands run without errors, then you’re ready to get exploring!

All communication with an ftrack server takes place through the Session object. To learn more about how this object works, see this documentation on understanding sessions.

5. Explore your project data

Ideally, your API credentials will allow you to read and write data to your server. While both are important, it is easiest to explore in read-only mode. So let’s write our first query and have a look around. But first, let’s take a look at all the “types” in our database. To do so, type the following in your iPython session:

In [3]: session.types.keys()
Out[3]: dict_keys(['Asset', 'Milestone', 'Task', 'Project', 'Note', ‘Shot', ‘Sequence'])

You’ll see a much longer list of types above, but the list is reduced here for the sake of simplicity.

At this point, be sure to familiarize yourself with ftrack’s excellent API reference, which is available in the Help section (top right corner) of your ftrack instance. You can always refer back to this resource as you explore using the API.

Let’s start with the Project type. Here’s a query to list all ftrack Studio projects:

In [4]: session.query("Project").all()
Out[4]:
[<dynamic ftrack Project object 4569254112>,
 <dynamic ftrack Project object 4568971584>,
 <dynamic ftrack Project object 4568970912>]

Better yet, let’s iterate over the results of this query by printing the “name” of each project in the results set with:

In [5]: projects = session.query(“Project”).all()
In [6]: [p["name"] for p in projects]
Out[6]:
[‘Demo Project’,
 ‘Avengers Movie',
 ‘Fender Commercial']

Let’s take the first project and explore some of its attributes and the entities they point to and continue down into the object tree as we explore:

In [7]: demo_project = projects[0]
Out[7]:
[('created_at', <Arrow [2020-05-19T10:19:07+00:00]>),
 ('managers', <ftrack_api.collection.Collection at 0x110648c70>),
 ('calendar_events', <ftrack_api.collection.Collection at 0x110557130>),
 ('color', '#FFEB3B'),
 ('_link',
[{'type': 'Project',
  'id': '2c5fc83e-99ba-11ea-9970-ca9d6ff8834e',
  'name': ‘Demo Project'}]),
 ('full_name', 'Demo Project'),
 ('disk', <dynamic ftrack Disk object 4936562864>),
 ('children', <ftrack_api.collection.Collection at 0x1105d1f70>),
 ('timelogs', <ftrack_api.collection.Collection at 0x1263dfc70>),
 ('end_date', <Arrow [2021-12-31T00:00:00+00:00]>),
 ('parent_id', None),
 ('created_by', <dynamic ftrack User object 4936948464>),
[…some output omitted…]

Now we see all the top-level attributes of our project and their respective types. We can access each of these attributes, and based on each subsequent entity type we can inspect or iterate down through the project’s hierarchy. For example, to see how many “Calendar Events” we have in the Demo Project, you can simply do this:

In [8]: len(demo_project[“calendar_events"])
Out[8]: 49

Once you’re comfortable querying for things (“reading”), then you can move on to modifying and creating things (“writing”). For that, we’ll direct you toward the API documentation. You can find a variety of links below to help you with your research.

Helpful resources

Below you can find some useful links and resources to use when exploring the ftrack API. We hope you enjoy the ftrack API and we hope you don’t hesitate to reach out with questions or feedback! You can connect with us at [email protected] or via our Twitter and Facebook pages.

Explore the ftrack API

Start your free ftrack Studio trial to see how the ftrack API can support your next project.

I'd like to try ftrack

More from the blog

What’s new in cineSync – a deeper iconik integration, laser tool, OTIOZ support, and more

| cineSync, New features, Product, Release | No Comments
cineSync's latest update brings flexibility and precision to your cineSync experience, making it easier to connect your review sessions with media management and storage in iconik, introducing color profiles to…

The Imaginarium Studios: Running a Thriving Motion Capture Studio with ftrack Studio

| Animation, Case Study, News, Q&A, Review, Studio | No Comments
Formed in 2012 by legendary actor and director Andy Serkis and led by CEO Matt Brown, The Imaginarium Studios is a performance-led capture and virtual production studio with facilities located…

ftrack achieves SOC 2 Security compliance for its project management and media review solutions

| Announcements, News, Product, Review, Security, Studio | No Comments
We’re pleased to announce the successful completion of ftrack’s independent SOC 2 audit, reaffirming the commitment, consideration, and care we continue to give to the security of your projects. For…

Chocolate Tribe Invests in South African Talent and Uses ftrack to Collaborate

| Animation, Case Study, News, Q&A, Studio | No Comments
The VFX and animation market in South Africa is about to explode–and Chocolate Tribe has already put the right tools, and team, in place to lead the way. Chocolate Tribe…
ftrack

Protecting Your Creative Vision During Desktop and Web-based Review & Approval

| cineSync, Product, Review, Tips & tricks | No Comments
When it comes to the question of security for media review solutions, how do we manage the balance between protecting the media, but still keeping the solutions simple and user…
Twilight POST

Twilight POST: On the Front Lines of India’s Expanding VFX and Animation Industry

| Animation, Case Study, News, Q&A, Studio | No Comments
As the world sits up and takes notice of cinematic marvels like K.G.F: Chapter 2 and RRR, it's clear that Indian cinema is a force to be reckoned with. VFX…

How to Bypass the 3 Mental Snags of Media Sequence Creation

| Animation, News, Review, Studio, Tips & tricks | No Comments
Forging a compelling media sequence in the fires of creativity and urgent deadlines is a craft that requires meticulous planning, seamless transitions, and an instinctive understanding of storytelling. Whether for…

How Cine Chromatix Automates Production Workflows with ftrack for Award-winning Work

| Case Study, News, Q&A, Review, Studio | No Comments
Racking up industry awards in VFX is just the beginning for Cine Chromatix.   Cine Chromatix is a full-service partner for feature films and series with an in-house VFX and…