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

Fika

How Fika Stays Nimble in the World of Virtual Production with ftrack

| Animation, Case Study, News, Studio | No Comments
Fika Entertainment is an Australian-based virtual production studio with a focus on animation production and VFX content that is accessible, fast and cost-effective. The company is passionate about helping clients…
pixel-zoo

The Secrets of Pixel Zoo’s New Workflow to Stay Ahead of the Creative Curve

| Animation, Case Study, Q&A, Studio | No Comments
Fueled by a unique blend of talents, cultural richness, and an environment of breathtaking landscapes and diverse wildlife, Australia’s creative industry is thriving more than ever before.    One gem…

The New Face of Media Management is Simple and Flexible

| cineSync, Integrations, New features, Product, Review | No Comments
We recently released cineSync 5.3, featuring a new integration with Backlight's flexible media asset management solution, iconik. Below, we take a closer look at iconik and how it can help…
ftrack 7 tips

7 Onboarding Tips for Production Tracking Tools

| News, Studio, Tips & tricks | No Comments
Content creation and collaboration have become a part of nearly every industry. Scalable and robust project management and production tracking solutions are needed to help companies ensure that their teams…

The new iconik x cineSync integration brings accessible media management to cineSync

| Announcements, cineSync, Integrations, News, Product, Release, Remote, Review | No Comments
cineSync 5.3 introduces a whole new way to manage your media and share files via the new cineSync x iconik integration. Below, we reveal why combining high-quality, secure media review…

Backlight unveils cineSync 5.3, with more ways to review media, faster

| cineSync, Integrations, New features, Product, Release, Review | No Comments
The latest update to cineSync 5 introduces an integration with Backlight’s media management solution iconik alongside more responsive and optimized reviews, empowering you to streamline your creative workflows and get…
CGEV

Reflecting on 10 years and 725 projects with ftrack Studio at France’s CGEV

| Case Study, News, Q&A, Review, Studio | No Comments
Over the past decade, Compagnie Générale des Effets Visuels (CGEV) has established a rock-solid reputation with work on feature films, series, and a surge of content for Netflix, Amazon, and…
creative_project_reports

How Creative Project Reports Will Win More Work for Your Studio

| Productivity, Review, Studio, Tips & tricks | No Comments
Data is the new gold. Since data gives you the raw materials to make informed decisions and chase the right opportunities, the more you have, the more successfully your studio…