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 versions) are the main UI representation when publishing files to ftrack. A version needs a parent entity that group different versions together and forms 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 folder.
If a task represents 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 transferred to its correct place and given its correct name. Often API clients have already been configured to automatically add components to the preferred location.
Tip: Here are some examples using the python client to publish versions.