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 optimisation 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 which 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.

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
  }
]
Did this answer your question?