Before you get into publishing via the API, please make sure you have a good understanding of the different ways to handle files and media in ftrack.

Files are represented as components in ftrack. Components can be associated with different entities in ftrack and represent thumbnails, attachments to notes or files on published versions.

Versions (also called asset version) are the main UI representation when publishing files to ftrack. A version needs a parent entity which group different versions together and form an asset. The asset entity holds information about the versions such as name and type.

Components are attached directly to the version and a version can have multiple components representing different files that belong to the same published version.

The asset entity should be attached to a context. A context is either a project or an object such as a shot, asset build or a folder.

If a task is representing the work that should be published, the task cannot be used as the parent of the asset. Instead the parent of the task should be used as the parent of the asset. The task itself should be associated directly with the version.

Here is an example of what it looks like:

When another version of the same asset is published it should be created with the already existing asset as its parent.

A components is the representation of a file, but only the metadata such as name, type and size. The actual existence of the file is represented by a ComponentLocation which represents a certain file in a certain location.

When you publish a version you also need to create the components and add the components to one or more locations which will make sure the file is transfered to its correct place and given its correct name. Often API clients have already been configured to automatically add components to the preferred location.

Here are some examples using the python client to publish versions.