Skip to main content

Tutorial

The API uses sessions to manage communication with an ftrack server. Create a session that connects to your ftrack server (changing the passed values as appropriate):

const session = new ftrack.Session(
  "https://my-company.ftrackapp.com",
  "john.doe@example.com",
  "7545344e-a653-11e1-a82c-f22c11dd25eq",
);

await session.initializing;

console.info("API session initialized successfully.");

If everything works as expected, you should see the console message appear in the JavaScript console. If not, double check that the credentials you specified are correct.

The communication with the ftrack server in the JavaScript API is asynchronous, often returning Promises. When the session is constructed, the instance is returned immediately, while the API is being initialized in the background. Once the API has been initialized, the session.initializing promise will be resolved.

Query projects​

Now, let’s start using the API with an example. Let’s list the names of all projects.

const response = await session.query("select name from Project");

const projects = response.data;
console.info("Listing " + projects.length + " projects");

console.log(projects.map((project) => project.name));

Each project returned will be a plain JavaScript object and contain the selected attributes.

The session contains a few other methods besides query(), such as create(), update() and delete(). Next up, let’s take a look at combining the query call with an update operation.

In the example below a specific project is retrieved, and then its status is set to hidden, hiding the project from the UI.

const projectName = "my_project";
const response = await session.query(
  "select id from Project where name is " + projectName,
);
const projectId = response.data[0].id;
const response = await session.update("Project", [projectId], {
  status: "hidden",
});

console.info("Project hidden", response);

Uploading files​

Files are stored as components in ftrack. Here is an example on how to create a component from a file in ftrack and upload it to the ftrack.server location.

const data = { foo: "bar" };
const file = new File([JSON.stringify(data)], "data.json");

const response = await session.createComponent(file);
const component = response[0].data;
console.log(component.id);