Overview

The API is available over HTTP with JSON used as the data transmission format.

For efficiency, the API operates in batch mode and is accessible via a single endpoint https://<SERVER_URL>/api.

A client should POST to that endpoint a JSON payload that describes a series of operations to perform.

Each request should also include the following headers:

Content-Type: application/json
Accept: application/json

As each request is considered a list of operations, the response is equally a list of results that correspond to the indices of the operations.

Authentication

To use the API you will need a valid username and API key. The username should match the username of an ftrack account holder that you wish to perform actions on behalf of via the API.

The API key can be either the private API key of that user found on their account page or a globally configured key available from System settings ‣ Security ‣ API keys.

API Authentication is then done using custom headers in the initial request:

ftrack-user: USERNAME
ftrack-api-key: API_KEY_TO_USE

The details are then stored for the rest of the session and only a standard session cookie is required.

If the details are invalid, the request will return an HTTP error status code, with details on why the authorization failed in the response body.

Example

The following shows an example ‘empty’ request and corresponding response.

Example request:

POST /api HTTP/1.1
Host: example.ftrackapp.com
Content-Type: application/json
Accept: application/json
ftrack-user: john
ftrack-api-key: cdd5dcbc-d0bd-435c-8f9d-6ed6902cdd9a

[]

Example response:

Cache-Control: no-cache
Connection: keep-alive
Content-Length: 2
Content-Type: text/html; charset=utf-8
Date: Tue, 17 Nov 2015 14:06:33 GMT
Pragma: no-cache
Server: nginx/1.6.1

[]

You can perform such a call using an HTTP client like cURL:

Note

Replace the header credentials with your own.

curl https://ftrack-test.ftrackapp.com/api \
    -X POST \
    -H "Content-Type: application/json" \
    -H "ftrack-user: john" \
    -H "ftrack-api-key: cdd5dcbc-d0bd-435c-8f9d-6ed6902cdd9a" \
    --data '[]'

[]

Errors

For authentication or exceptional errors a standard HTTP error code will be returned with details in the body and also in an FTRACK_ERROR header.

In the case of an operational error occurring the response payload will take the form of a dictionary:

{
    'exception': 'ExceptionName',
    'content': 'Exception details'
}