So you’ve decided you want to talk to the Flix Client API. This step-by-step guide will go through the steps required to register a new application - “My First Flix Extension” - with Flix and get you cracking on your integrations!

Step 1: Create an extension identity

The first thing every Flix Client extension needs is an identity. This means the extension needs a name, a version, and a unique identifier. We already have a name for our extension, “My First Flix Extension”, and as this is our first version we can call it v1.0.0. The only thing remaining is to create a unique identifier for the extension. We can use the UUID standard to generate a string that is unlikely to ever be duplicated by accident. Let’s go with 490a3e7e-fd22-467a-8169-cdc5b69b6175 for now, but you should generate your own.

Step 2: Check the Flix Client is running

Before we start sending off API requests, we should first check that the Flix Client is up and running. We can do this by sending a GET request to http://localhost:3000/health. If the Flix Client is up and running correctly, we should get back a 200 OK response with no additional content. If any other response comes back, or the request doesn’t complete, something is up with the Flix Client that likely requires some user intervention.

Step 3: Register with Flix

Now that we’ve got all the identifying details we need and we know the Flix Client is running, let’s register with it. We can do this having our extension send a POST request to http://localhost:3000/registration with this request body:

{
  "name": "My First Flix Extension",
  "clientUid": "490a3e7e-fd22-467a-8169-cdc5b69b6175",
  "version": "1.0.0"
}

If we print out the response we get:

{
  "flixId": 18,
  "token": "BZIu4t8JyMpObY6HVUnt1u7IlIvkQWw-n-mSIxhDUTU"
}

We don’t need the flixId right now, but let’s make sure we store that token for later.

Step 4: Check for access

Now that Flix knows about our extension, we should be able to access any endpoint of the Flix Client API. We can check this using the token it gave us. We’ll need to set the token as a Bearer auth header, so let’s do that by adding to our list of headers:

Authorization: BEARER BZIu4t8JyMpObY6HVUnt1u7IlIvkQWw-n-mSIxhDUTU

Then, we can do a quick request to the status endpoint to see what state the Flix Client is in. This is just a GET request to http://localhost:3000/status with the extra header from above. When everything works, we should see a JSON response like the following:

{
  "canCreate": true,
  "revisionStatus": {
    "canPublish": true,
    "canExport": true,
    "canSave": false,
    "selectedPanels": [1]
  },
  "actionsInProgress": {
    "isSaving": false,
    "isPublishing": false,
    "isExporting": false
  }
}

Step 5: All done

That’s it! You’re now ready to interact with the Flix Client and ready to turn “My First Flix Extension” into the best thing ever. Although, maybe come up with a better name first.

The health check endpoint is a basic test entrypoint for the Flix Client API and will always return a 200 OK response when the API is available. This endpoint can be used as a sanity check to validate connections to Flix before first connecting or after a disconnect.

Most of the Flix Client API is gated behind a simple API registration process. Each API consumer must first register with Flix by sending a POST request to http://localhost:3000/registration. The token in the registration response should be attached as a bearer token in the authorization header with future requests. To validate the registration, do a GET request to the same registration endpoint along with the auth header, and the registered API consumer details should be returned.

To unregister an API consumer, do a DELETE request to the same registration endpoint. This will invalidate the registration token and remove the registered API consumer details from the Flix client.

The clientUid that is specified with the registration should be the same as specified in the extension manifest file when packaging the extension. This should remain the same throughout the lifetime of the extension as it is used to compare extensions at registration and install time.

The status endpoint provides details on the current state of the Flix Client. It can be used to determine the auth status of the current user, and whether there are any other ongoing actions that may impact the use of the API.

The project endpoints provide details on the current state of the Flix Client. It can be used to determine the currently opened show, episode, sequence and sequence revision.

The panels endpoint provides the ability to create, update and add annotations to panels in the sequence revision that is currently open in the Flix Client. This requires the Flix Client to have a sequence revision loaded in order to function and will return a 400 Bad Request error if that is not the case. The current Flix status can be checked using the project and status endpoints.

To create a new panel, send a POST request to the /panels endpoint with an object containing a paths property that is an array of strings that are paths to the artworks to be imported. Flix will then schedule a background action to import the specified artworks to the active sequence revision. The request will return an object containing the action ID of the scheduled action and will send updates through the websocket event gateway.

Updating panels or adding annotations works in the same way, but for PATCH requests to the /panels endpoint and /panels/annotate endpoints respectively. These requests also support specifying which panels should be updated or annotated by sending an object containing a panels property that is an array of objects specifying a panel ID and a path. These requests will also schedule a background action and return an object containing the action ID.

All of the panel actions require an origin property to be specified in the request body that is associated with the new panel revision and should specify where the panel originated. They also all accept an optional startIndex property that specifies at which index panels should be inserted/updated from. By default actions will use the currently selected panel as that start index. At the time of writing, this is the currently selected panel at the start of execution of the action. Since actions are queued and run sequentially, this may not be the same panel as the one selected at request time.

Finally, the create and update panel requests support including a sourceFile property. This is an object that should specify the path to the source file, a previewMode that tells Flix how to generate a preview for the source file, and the sourceFileType which Flix uses to determine how to open the source file. Valid previewMode options are first_panel which tells Flix to use the first associated panel’s thumbnail as the source file preview image, and source_file which tells Flix to try to generate a thumbnail preview image from the source file directly. The sourceFileType can be any of the defined extension types, Sketch, Editorial, 3D, Standalone, or Script. Only Sketch or 3D type source files can currently be re-opened by Flix.

The download endpoint provides the ability for an extension to request a specific asset from the Flix Server and have the Flix Client download it to a specified location. Before using this endpoint, you will need to figure out the ID of the asset to be downloaded and the type of the media object required, either using the other API endpoints or from the Flix Server API. Requests to the download API endpoint will begin the download immediately and will not complete until the download has finished, which means the request may be long-lived.