{"id":17508208,"url":"https://github.com/ftrackhq/ftrack-javascript","last_synced_at":"2026-02-05T00:03:46.354Z","repository":{"id":54650459,"uuid":"521600510","full_name":"ftrackhq/ftrack-javascript","owner":"ftrackhq","description":"Official ftrack JavaScript API client","archived":false,"fork":false,"pushed_at":"2026-01-14T12:22:29.000Z","size":7787,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-14T14:34:23.486Z","etag":null,"topics":["api","client","ftrack","javascript","javascript-client","sdk"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ftrackhq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-08-05T10:45:00.000Z","updated_at":"2026-01-14T12:22:03.000Z","dependencies_parsed_at":"2024-02-01T22:38:21.739Z","dependency_job_id":"7ad6abfc-a103-4c50-a794-341af9643d5f","html_url":"https://github.com/ftrackhq/ftrack-javascript","commit_stats":{"total_commits":356,"total_committers":18,"mean_commits":19.77777777777778,"dds":0.6769662921348314,"last_synced_commit":"13479dd4554dd9b19876317ba7d826f8d53525f4"},"previous_names":["ftrackhq/javascript-api"],"tags_count":72,"template":false,"template_full_name":null,"purl":"pkg:github/ftrackhq/ftrack-javascript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftrackhq%2Fftrack-javascript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftrackhq%2Fftrack-javascript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftrackhq%2Fftrack-javascript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftrackhq%2Fftrack-javascript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ftrackhq","download_url":"https://codeload.github.com/ftrackhq/ftrack-javascript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftrackhq%2Fftrack-javascript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","ftrack","javascript","javascript-client","sdk"],"created_at":"2024-10-20T04:13:07.335Z","updated_at":"2026-01-16T10:56:01.850Z","avatar_url":"https://github.com/ftrackhq.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ftrack JavaScript API Client\n\nThe ftrack JavaScript API Client is a JavaScript Library to help developing integrations that communicate with the ftrack API and Event server.\n\nThis documentation focuses on the client. More information about the API and its concepts can be found at our [general API documentation](https://help.ftrack-studio.backlight.co/hc/en-us/categories/13129800014999-Development-API). You may also find it useful to look at the documentation for the [Python client](https://github.com/ftrackhq/ftrack-python).\n\n- [Installation](#installation)\n- [Tutorial](#tutorial)\n  - [Query projects](#query-projects)\n  - [Uploading files](#uploading-files)\n- [Handling Events](#handling-events)\n  - [Connecting to event hub](#connecting-to-event-hub)\n  - [Error handling](#error-handling)\n  - [Subscribing to events](#subscribing-to-events)\n  - [Subscriber information](#subscriber-information)\n  - [Sending replies](#sending-replies)\n  - [Publishing events](#publishing-events)\n  - [Handling replies](#handling-replies)\n  - [Limitations](#limitations)\n  - [Methods](#methods)\n  - [Further documentation](#further-documentation)\n\n## Installation\n\nnpm:\n\n```bash\nnpm install @ftrack/api\n```\n\nyarn:\n\n```bash\nyarn add @ftrack/api\n```\n\n## TypeScript: Generated Schema Types\n\nYou can generate schema types for your own workspace with [@ftrack/ts-schema-generator](https://github.com/ftrackhq/ftrack-ts-schema-generator).\n\nOnce generated, you can integrate them with @ftrack/api by passing them as a type variable:\n\n```ts\nimport { EntityTypeMap } from \"./__generated__/schema.ts\";\nimport { Session } from \"@ftrack/api\";\n\nconst session = new Session\u003cEntityTypeMap\u003e(...);\n\n// user will now be of type User\n// and provide all available properties for its entity type.\nconst user = await session.query\u003c\"User\"\u003e(\"...\");\n```\n\n## Tutorial\n\nThe 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):\n\n```javascript\nconst session = new ftrack.Session(\n  \"https://my-company.ftrackapp.com\",\n  \"john.doe@example.com\",\n  \"7545344e-a653-11e1-a82c-f22c11dd25eq\",\n);\n\nawait session.initializing;\n\nconsole.info(\"API session initialized successfully.\");\n```\n\nIf 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.\n\nThe 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.\n\n### Query projects\n\nNow, let’s start using the API with an example. Let’s list the names of all projects.\n\n```javascript\nconst response = await session.query(\"select name from Project\");\n\nconst projects = response.data;\nconsole.info(\"Listing \" + projects.length + \" projects\");\n\nconsole.log(projects.map((project) =\u003e project.name));\n```\n\nEach project returned will be a plain JavaScript object and contain the selected attributes.\n\nThe session contains a few other methods besides `query()`, such as `create()`, `update()` and `delete()`.\nNext up, let’s take a look at combining the query call with an update operation.\n\nIn the example below a specific project is retrieved, and then its status is set to hidden, hiding the project from the UI.\n\n```javascript\nconst projectName = \"my_project\";\nconst response = await session.query(\n  \"select id from Project where name is \" + projectName,\n);\nconst projectId = response.data[0].id;\nconst response = await session.update(\"Project\", [projectId], {\n  status: \"hidden\",\n});\n\nconsole.info(\"Project hidden\", response);\n```\n\n### Uploading files\n\nFiles 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.\n\n```javascript\nconst data = { foo: \"bar\" };\nconst file = new File([JSON.stringify(data)], \"data.json\");\n\nconst response = await session.createComponent(file);\nconst component = response[0].data;\nconsole.log(component.id);\n```\n\n## Handling Events\n\nThe `EventHub` is a class that provides functionality to interact with an ftrack event server. It allows you to connect to the event server, subscribe to specific events, publish events, and handle event responses.\n\nEvents are generated in ftrack when things happen such as a task being updated or a new version being published. Each Session can optionally connect to the event server and can be used to subscribe to specific events and perform an action as a result. That action could be updating another related entity based on a status change or generating folders when a new shot is created for example.\n\nThe `EventHub` for each Session is accessible via `session.eventHub`.\n\n### Connecting to event hub\n\nTo connect to the event hub, run `session.eventHub.connect()`. You can also automatically connect the event hub when it is instantiated by providing the option `autoConnectEventHub` when constructing the Session instance:\n\n```javascript\nsession = new ftrack.Session(..., { autoConnectEventHub: true });\nsession.eventHub.isConnected();\n```\n\n### Subscribing to events\n\nTo listen to events, you register a function against a subscription using ’Session.eventHub.subscribe()’. The subscription uses the expression syntax and will filter against each Event instance to determine if the registered function should receive that event. If the subscription matches, the registered function will be called with the Event instance as its sole argument. The Event instance is a mapping like structure and can be used like a normal object.\n\nThe following example subscribes a function to receive all ‘ftrack.update’ events and then print out the entities that were updated:\n\n```javascript\nimport { Session } from \"@ftrack/api\";\n\n// Define a function to handle the received event\nfunction myCallback(event) {\n  // Iterate through the updated entities and print their data\n  event.data.entities.forEach((entity) =\u003e {\n    // Print data for the entity\n    console.log(entity);\n  });\n}\n\n// Create a session and automatically connect to the event hub\nconst session = new Session({ autoConnectEventHub: true });\n\n// Subscribe to events with the 'ftrack.update' topic\nsession.eventHub.subscribe(\"topic=ftrack.update\", myCallback);\n```\n\n### Subscriber information\n\nWhen subscribing, you can also specify additional information about your subscriber. This contextual information can be useful when routing events, particularly when targeting events. By default, the event hub will set some default information, but it can be useful to enhance this. To do so, simply pass in _subscriber_ as a object of data to the\n`subscribe()` method:\n\n```javascript\nsession.eventHub.subscribe(\"topic=ftrack.update\", myCallback, {\n  id: \"my-unique-subscriber-id\",\n  applicationId: \"maya\",\n});\n```\n\n### Sending replies\n\nWhen handling an event it is sometimes useful to be able to send information back to the source of the event. For example, `ftrack.location.request-resolve` would expect a resolved path to be sent back.\n\nYou can publish a custom reply event using `publishReply()`, but an easier way is to return the appropriate data from your handler. Any returned value except _null_ or _undefined_ will be automatically sent as a reply:\n\n```javascript\nfunction onEvent(event) {\n  // Send following data in automatic reply\n  return { success: true, message: \"Cool!\" };\n}\n\nsession.eventHub.subscribe(\"topic=test-reply\", onEvent);\n```\n\n### Publishing events\n\nSo far we have looked at listening to events coming from ftrack. However, you are also free to publish your own events (or even publish relevant ftrack events).\n\nTo do this, simply construct an instance of `Event` and pass it to `EventHub.publish()` via the session:\n\n```javascript\nimport { Event } from \"@ftrack/api\";\n\nevent = new Event((topic = \"my-company.some-topic\"), (data = { key: \"value\" }));\nsession.eventHub.publish(event);\n```\n\nThe event hub will automatically add some information to your event before it gets published, including the source of the event. By default the event source is just the event hub, but you can customise this to provide more relevant information if you want.\n\n### Handling replies\n\nWhen publishing an event, you can specify `onReply` as a function which will be invoked whenever a reply event is received:\n\n```javascript\nfunction onReply(event) {\n  console.info(\"Reply received\", event.data);\n}\nsession.eventHub.publish(event, { onReply: onReply });\n```\n\nIt is often the case that you want to wait for a single reply. In this case, you can use the convenience method `publishAndWaitForReply()`. It will return a promise which will be resolved with the response. You can test this using two browser tabs. In the first, run the following to listen for event and reply:\n\n```javascript\n// Listen for events and reply\nfunction onEvent(event) {\n  console.info(\"Event received\", event.data);\n  return { message: \"Event acknowledged\" };\n}\nsession.eventHub.subscribe(\"topic=my-company.some-topic\", onEvent);\n```\n\nIn the second environment we will publish an event, wait for and log the response:\n\n```javascript\n// Publish event and wait for reply\nfunction onReply(event) {\n  console.info(\"Promise resolved with reply\", event.data);\n}\nfunction onError(error) {\n  console.error(\"Reply not received\", error);\n}\nvar event = new ftrack.Event(\"my-company.some-topic\", {\n  message: \"Hello world!\",\n});\nsession.eventHub\n  .publishAndWaitForReply(event, { timeout: 5 })\n  .then(onReply, onError);\n```\n\n### Limitations\n\nThe event hub in the JavaScript API has some minor differences and lacks some\nof the features available in the [python counterpart](https://ftrack-python-api.rtd.ftrack.com/en/latest/handling_events.html).\n\n#### Subscription expressions\n\nThe JavaScript API currently only support expressions on the format `topic=value` including wildcard support `topic=ftrack.*`, and more complex expressions such as filtering based on event source or data are not supported.\n\n#### Target expression\n\nTargeted events will invoke all subscribers of the topic, not just those matching the target expression.\n\n#### Stopping events\n\nSubscription callback priorities and the ability to stop events is not supported at this point.\n\n### Methods\n\n#### `connect()`\n\nConnects to the event server.\n\n```javascript\nsession.eventHub.connect();\n```\n\n#### `isConnected(): boolean`\n\nChecks if the `EventHub` is connected to the event server.\n\n```javascript\nconst isConnected = session.eventHub.isConnected(); // Returns true if connected, false otherwise\n```\n\n#### `publish(event: Event, options?: { onReply?: EventCallback, timeout?: number }): Promise\u003cstring\u003e`\n\nPublishes an event to the event server and returns a promise resolved with the event ID when the event is sent.\n\n- `event` (Event): An instance of the `Event` class to publish.\n- `options.onReply` (EventCallback, optional): A function to be invoked when a reply is received.\n- `options.timeout` (number, optional): Timeout in seconds (default is 30 seconds).\n\nExample:\n\n```javascript\nconst event = new Event(/* ... */);\nsession.eventHub.publish(event, {\n  onReply: (reply) =\u003e {\n    // Handle the reply event\n  },\n  timeout: 60,\n});\n```\n\n#### `publishAndWaitForReply(event: Event, options: { timeout: number }): Promise\u003cunknown\u003e`\n\nPublishes an event and waits for a single reply event.\n\n- `event` (Event): An instance of the `Event` class to publish.\n- `options.timeout` (number): Timeout in seconds for waiting for a reply event.\n\nReturns a promise resolved with the reply event payload when received or rejects if no reply event is received within the specified timeout.\n\nExample:\n\n```javascript\nconst event = new EventEvent(\n  (topic = \"my-company.some-topic\"),\n  (data = { key: \"value\" }),\n);\nsession.eventHub\n  .publishAndWaitForReply(event, { timeout: 60 })\n  .then((replyEvent) =\u003e {\n    // Handle the reply event\n  });\n```\n\n#### `subscribe(subscription: string, callback: EventCallback, metadata?: SubscriberMetadata): string`\n\nSubscribes to events matching a specified subscription expression.\n\n- `subscription` (string): The subscription expression in the format \"topic=value\" or with wildcards like \"topic=ftrack.\\*\".\n- `callback` (EventCallback): A function to be called when an event matching the subscription is received. Callbacks can either be synchronous or asynchronous function.\n- `metadata` (SubscriberMetadata, optional): Optional metadata about the subscriber.\n\nReturns a subscriber ID, which can be used to unsubscribe from events later.\n\nExample:\n\n```javascript\nconst subscriberId = session.eventHub.subscribe(\n  \"topic=ftrack.action.launch\",\n  (eventPayload) =\u003e {\n    // Handle the received event\n  },\n);\n```\n\n#### `unsubscribe(identifier: string): boolean`\n\nUnsubscribes from events based on a subscriber ID returned from the `subscribe` method.\n\n- `identifier` (string): The subscriber ID to unsubscribe.\n\nReturns `true` if a subscriber was removed, `false` otherwise.\n\nExample:\n\n```javascript\nconst subscriberId = session.eventHub.subscribe(/* ... */);\nconst unsubscribed = session.eventHub.unsubscribe(subscriberId);\nif (unsubscribed) {\n  console.log(`Unsubscribed subscriber with ID: ${subscriberId}`);\n} else {\n  console.log(`Subscriber with ID ${subscriberId} not found.`);\n}\n```\n\n#### `getSubscriberByIdentifier(identifier: string): Subscriber | null`\n\nReturns information about a subscriber based on its identifier.\n\n- `identifier` (string): The subscriber identifier.\n\nReturns a `Subscriber` object if found, or `null` if no subscriber with the specified identifier exists.\n\nExample:\n\n```javascript\nconst subscriberId = session.eventHub.subscribe(/* ... */);\nconst subscriber = session.eventHub.getSubscriberByIdentifier(subscriberId);\nif (subscriber) {\n  console.log(\"Subscriber information:\", subscriber);\n} else {\n  console.log(`Subscriber with ID ${subscriberId} not found.`);\n}\n```\n\n### Further documentation\n\nIf there's any part of the client that you would like us to expand the documentation for, please add a GitHub issue and we'll try to get to it as soon as possible. Otherwise more information about the API and its concepts can be found at our [general API documentation](https://help.ftrack.com/en/collections/133732-developing-with-ftrack-studio). You may also find it useful to look at the documentation for the [Python client](https://github.com/ftrackhq/ftrack-python).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fftrackhq%2Fftrack-javascript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fftrackhq%2Fftrack-javascript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fftrackhq%2Fftrack-javascript/lists"}