The following is a list of operations understood by the server with examples of the expected request payload followed by an example response.
In each case only the specific operation payload is shown, but keep in mind that an operation must always be included in a list. If you haven’t already, read the Overview to see a full example of a request.
Typically the first operations performed by a client would be to Query server information and check the server version is compatible, followed by fetching the schemas that outline valid entity types and attributes.
Query server information
Request basic information about the server, including server version.
Request
action
The action name. Must be query_server_information.
values
An array of information values to retrieve from server. Will use a default list of values if omitted.
[
{
"action": "query_server_information",
"values": ["schema_hash", "is_timezone_support_enabled", "storage_scenario"]
}
]Response
version
The server version in the format MAJOR.MINOR.PATCH.BUILD.
schema_hash
An MD5 message digest of the Query schemas response. Can be used as an optimization to avoid unnecessary Query schemas operation if schemas cached locally.
is_timezone_support_enabled
If timezones are enabled on server. If timezones are enabled, all datetime data is assumed to be in UTC and otherwise in the servers local time.
storage_scenario
Storage scenario configuration for automatic setup of API Location plugin.
[
{
"version": "3.3.13.4254",
"schema_hash": "3d369c2c9abf9cf59408d4c186e8bcd1",
"is_timezone_support_enabled": true
}
]Query schemas
Request list of Schemas that describe entity types available.
Request
action
The action name. Must be query_schemas.
[
{
"action": "query_schemas"
}
]Response
The response will be an array of objects describing entity schemas. A schema defines the available entity types, their attributes, and valid values. Each schema definition roughly follows the JSON-schema specification.
Note how a schema can reference another schema using $ref. In the example below, the TypedContext has a property called parent that references a Context entity.
[
[
{
"id": "TypedContext"
"type": "object",
"alias_for": "Task",
"polymorphic_identifier": "context_type",
"primary_key": [
"id"
],
"default_projections": [
"context_type",
"id",
"name"
],
"required": [
"bid",
"status_id",
"type_id",
"priority_id",
"object_type_id",
"sort",
"context_type",
"id",
"name"
],
"immutable": [
"id",
"_link",
"link"
],
"properties": {
"id": {
"default": "{uid}",
"type": "string"
},
"name": {
"default": "",
"type": "string"
},
"parent_id": {
"type": "string",
"description": "Foreign key(s): Context.id",
"format": "foreign_key"
},
"parent": {
"$ref": "Context"
}
}
}
]
]Query
Retrieve a selection of entities matching some criteria.
Request
action
The action name. Must be query.
expression
The expression. See Query Syntax for details on expression syntax.
[
{
"action": "query",
"expression": "select id, status from Job where type is \"api_job\" limit 1"
}
]Response
action
The name of the action executed.
data
List of dictionaries representing entities that match the supplied expression. Each dictionary will contain special __entity_type__ key that indicates the entity type.
metadata
Additional information, such as the adjusted next offset. The offset takes culling based on permissions into account and can be useful when paging results.
[
{
"action": "query",
"data": [
{
"status": "queued",
"__entity_type__": "Job",
"id": "dc041911-c69b-11e5-83b2-3c0754289fd3"
}
],
"metadata": {
"next": {
"offset": 1
}
}
}
]Create
Create a new entity.
| Please note: Typically a client should generate primary keys locally to allow construction of relationships prior to submitting creation request. |
Request
action
The action name. Must be create.
entity_type
Type of entity to create.
entity_data
Dictionary of initial data to create entity with. Must contain special __entity_type__ key that indicates the entity type.
[
{
"action": "create",
"entity_type": "Job",
"entity_data": {
"__entity_type__": "Job",
"type": "api_job"
}
}
]Response
action
The name of the action executed.
data
Dictionary representing the created entity. Will contain special __entity_type__ key that indicates the entity type. Note that the response may also include additional attribute values that were generated server side.
[
{
"action": "create",
"data": {
"status": "queued",
"__entity_type__": "Job",
"type": "api_job",
"id": "dc041911-c69b-11e5-83b2-3c0754289fd3"
}
}
]Update
Update attribute values on an existing entity.
Request
action
The action name. Must be update.
entity_type
Type of entity to update.
entity_key
Primary key(s) of entity to update.
entity_data
Data to update. Attributes not included will remain unchanged.
[
{
"action": "update",
"entity_type": "Job",
"entity_key": ["dc041911-c69b-11e5-83b2-3c0754289fd3"],
"entity_data": {
"status": "running"
}
}
]Response
action
The name of the action executed.
data
Dictionary representing the updated entity. Will contain special __entity_type__ key that indicates the entity type.
[
{
"action": "update",
"data": {
"status": "running",
"__entity_type__": "Job",
"id": "dc041911-c69b-11e5-83b2-3c0754289fd3"
}
}
]Delete
Delete an entity. May also automatically delete related entities to maintain integrity.
Request
action
The action name. Must be delete.
entity_type
Type of entity to delete.
entity_key
Primary key(s) of entity to delete.
[
{
"action": "delete",
"entity_type": "Job",
"entity_key": ["dc041911-c69b-11e5-83b2-3c0754289fd3"]
}
]Response
action
The name of the action executed.
data
Should contain true if the deletion was successful.
[
{
"action": "delete",
"data": true
}
]Get widget url
Return an authenticated URL for widget with name and given options. The returned URL will be authenticated using a token which will expire after 6 minutes.
Request
action
The action name. Must be get_widget_url.
name
Name of the widget to return. Should be one of info, tasks or tasks_browser.
entity_type
Certain widgets require an entity to be specified. If so, specify the entity type as entity_type.
entity_key
Certain widgets require an entity to be specified. If so, specify the primary key(s) as entity_key.
theme
Sets the theme of the widget and can be either ‘light’ or ‘dark’ (defaulting to ‘dark’ if an invalid option given).
[
{
"action": "get_widget_url"
}
]Response
widget_url
An authenticated URL for the widget.
[
{
"widget_url": "https://my-company.ftrackapp.com/widget/..."
}
]Encode media
Create an encoding job to encode a component to a web playable format. Encoded components can be retrieved from the returned job’s job_components relation.
Request
component_id
The id of the component to encode.
keep_original
Set to true if the component should be kept after completion of the encoding.
version_id
Optional version_id that will be set on the generated components.
[
{
"action": "encode_media",
"component_id": "bc041911-c69b-11e5-83b2-3c3754289fd3",
"keep_original": true,
"version_id": "dc041911-c69b-11e5-83b2-3c0754289fd3"
}
]Response
ob_id
The id of the created encoding job.
[
{
"job_id": "dc041911-c69b-11e5-83b2-3c0754289fd3"
}
]Get upload metadata
Return URL and headers used to upload data for component_id.
The returned URL should be requested using HTTP PUT with the specified headers.
The component_id does not have to be persisted. In that case, file_name and file_size must be specified. They will be fetched from the component if not set.
The checksum is used as the Content-MD5 header and should contain the base64-encoded 128-bit MD5 digest of the message (without the headers) according to RFC 1864. This can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, we recommend using the checksum mechanism as an end-to-end integrity check.
Request
component_id
The id of the component for which to upload data. Does not have to be persisted.
file_name
File name (including extension), optional if component is persisted.
file_size
File size (in bytes), optional if component is persisted.
checksum
Base64-encoded 128-bit MD5 digest of the data.
[
{
"action": "get_upload_metadata",
"component_id": "bc041911-c69b-11e5-83b2-3c3754289fd3",
"file_name": "image.jpeg",
"file_size": "452012",
"checksum": "O7+0vYGsWWd2eU7s5+487w=="
}
]Response
component_id
Id of the component. Does not have to be persisted.
url
URL to call using HTTP PUT with the component data.
headers
Object with headers which should be included in when making the PUT request.
[
{
"component_id": "bc041911-c69b-11e5-83b2-3c3754289fd3",
"url": "https://hostname.example.com/signed/put/url?param=value...",
"headers": {
"Content-Type": "image/jpeg",
"Content-Disposition": "attachment; filename=\"image.jpg\"",
"Content-MD5": "O7+0vYGsWWd2eU7s5+487w=="
}
}
]Reset Remote
Perform a server side reset, currently only the User entity attribute api_key is supported. This operation was added in ftrack version 3.5.18.
Request
action
The action name. Must be reset_remote.
reset_type
The type of reset to perform, currently only "api_key" and "password" are supported.
entity_type
The type of entity to perform the operation on.
entity_key
Primary key(s) of entity to delete.
entity_data
Optional data to pass to the reset_type operation.
[
{
"action": "reset_remote",
"reset_type": "api_key",
"entity_type": "User",
"entity_key": ["dc041911-c69b-11e5-83b2-3c0754289fd3"]
}
]Response
action
The name of the action executed.
data
Should contain true if the deletion was successful.
[
{
"action": "reset_remote",
"data": {
"api_key": "23e3aa06-f3d4-43fa-9554-27085b2862aa"
}
}
]Send review session invite
Send a review session invitee email to invitee_id.
Request
review_session_invitee_id
The id of the review session invitee which the email should be sent to.
[
{
"action": "send_review_session_invite",
"review_session_invitee_id": "aaab911-c69b-11e5-83b2-3c3754289fd3"
}
]Response
sent
Should contain true if the invitation was sent successfully.
[
{
"sent": true
}
]Parse query
Validate expression and return any error messages.
Request
expression
Expression to validate
[
{
"action": "parse_query",
"expression": ""
}
]Response
data
true or error message when parsing expression.
[
{
"action": "parse_query",
"data": true
}
]Add user security role
Add a security role to a user.
Request
user_id
The id of the user.
role_id
The id of the security role.
[
{
"action": "add_user_security_role",
"user_id": "",
"role_id": ""
}
]Response
success
true or error will be raised.
[
{
"action": "add_user_security_role",
"success": true
}
]Remove user security role
Remove a security role from a user.
Request
user_id
The id of the user.
role_id
The id of the security role.
[
{
"action": "remove_user_security_role",
"user_id": "",
"role_id": ""
}
]Response
success
true or error will be raised.
[
{
"action": "remove_user_security_role",
"success": true
}
]Update user security role
Update/replace a security role from a user. The role will be changed by keep access to the same projects.
Request
user_id
The id of the user.
role_id
The id of the current security role.
new_role_id
The id of the new security role.
[
{
"action": "update_user_security_role",
"user_id": "",
"role_id": "",
"new_role_id": ""
}
]Response
success
true or error will be raised.
[
{
"action": "update_user_security_role",
"success": true
}
]Grant user access to project for role
Give a user access to a project or all open projects for a security role.
Request
user_id
The id of the user.
role_id
The id of the security role.
all_open_projects (Optional) Can be provided instead of role_id to give access for all open projects for this role. Value should always be true if set.
project_id (Optional) Can be provided to instruct ftrack to grant security role for a specific project.
[
{
"action": "grant_user_security_role_project",
"user_id": "",
"role_id": ""
}
]Response
success
true or error will be raised.
[
{
"action": "grant_user_security_role_project",
"success": true
}
]Revoke user access to project for role
Remove access for a user and project or all open projects for a security role.
Request
user_id
The id of the user.
role_id
The id of the security role.
all_open_projects (Optional)
Can be provided instead of role_id to remove access from all open projects for this role. Value should always be true if set.
project_id (Optional) Can be provided to instruct ftrack to revoke security role for a specific project.
[
{
"action": "revoke_user_security_role_project",
"user_id": "",
"role_id": ""
}
]Response
success
true or error will be raised.
[
{
"action": "revoke_user_security_role_project",
"success": true
}
]Get storage usage
Get storage usage for project or location in bytes.
Request
entity_id
The id of the entity.
entity_type
The entity type (Project, Location)
[
{
"action": "storage_usage",
"entity_id": "PROJECT_ID",
"entity_type": "Project"
}
]Response
[
{
"action": "storage_usage",
"data": 40148870.0
}
]Get signed review URL
Get a signed URL to a review that can be shared with users.
Request
entity_key
The id of the entity.
entity_type
The entity type (ReviewSession)
[
{
"action": "generate_signed_url",
"entity_key": ["REWIEW_SESSION_ID"],
"entity_type": "ReviewSession"
}
]Response
[
{
"action": "storage_usage",
"signed_url": ""
}
]