Operations¶

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

job_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=="
    }
  }
]

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
  }
]

Send User invite¶

Send a invitation email to user_id

Request

user_id:	The id of the user you wish to send a invitation to.

[
  {
    "action": "send_user_invite",
    "user_id": "cccb911-s69b-35e5-64b2-3a3424225hg4"
  }
]

Response

sent:	Should contain true if the invitation was sent successfully.

[
  {
    "sent": true
  }
]

Execute delayed job¶

Trigger a operation on the server such as synchronizing users with LDAP.

Request

job_type:	The string id of the task to run. Currently only “SYNC_USERS_LDAP” is supported.

[
    {
        "action": "delayed_job",
        "job_type": "SYNC_USERS_LDAP"
    }
]

Response

action:	The name of the action executed.
data:	Dictionary representing a newly created Job entity.

[
    {
        "action": "delayed_job",
        "data": {
          "__entity_type__": "Job",
          "id": "dc041911-c69b-11e5-83b2-3c0754289fd3"
        }
    }
]

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
  }
]