GDTF Share API Documentation


The GDTF Share provides a REST Web API that allows users to login, view the existing fixtures, and download any revisions without needing a web browser to access the GDTF Share website.

This API provides three functions:

  • Login: Using the username and password from the account registered at the GDTF Share.
  • Get List: Revision listing with a simple versioning hash.
  • Download: Download file using the Revision ID.

The indivitual functions are described in the chapter Functions.

Use cases

This API is provided for the convenience of users who want to integrate the GDTF Share into their own applications, but it is not intended to be used as a replacement for the GDTF Share website. It aims to provide a simple way to access the GDTF Share functionality for the following use cases:

  • Application developers who do not want to include a full web browser in their products, but prefer to implement the functionality of the GDTF Share directly.
  • Console and application designers who want to design their own user interface, for example, for login, listing or download.
  • Integration of the GDTF database into the fixture type patching process.


1. GDTF Share User Account

A GDTF Share account is required for users to access the functionality provided by the API. If the user is not registered, they should be directed to to create a free account.

The GDTF Share and the API are not accessible to users who do not have a registered account. If you are not the end user, you should direct your customers who wish to use this functionality to the GDTF Share website to create an account.

2. Software

The API requires the usage of any client that supports Web APIs, for example, CURL, which supports a wide variety of operating systems and platforms. To learn more about Web APIs, please visit:

3. Cookies

A session cookie is required to ensure each request is authenticated. If the cookie is not used between requests, the user will not have permissions to access any functions. This cookie has a timeout of 2 hours. If the cookie is not used within this time, the user will need to login again.

Examples of how to use a cookie file with CURL are provided in the sample requests. If you wish to know more about cookies, please visit:



This function allows the user login by username and password.

MethodContent typePath


userRequiredUsername as registered in the GDTF Share.String
passwordRequiredPassword of the user account.String


Content typeHTTP Status codes
application/json200, 400, 401

Sample request

curl    -c session.txt -L -X POST
        -H 'Content-Type: application/json'
        -d '{"user":"Real User 42", "password":"123SafePassw0rd456"}'

Sample response

On success: HTTP Code 200

{"result":true, "notice":"Welcome! Why did the coffee file a police report?  It got mugged."}

On error: HTTP Code 401

{"result":false, "error":"No valid user or password provided."}

Get List

This function allows a user to get the list of revisions.



This function does not require any parameters.


Content typeHTTP Status codes
application/json200, 400, 401, 500

Sample request

curl    -b session.txt

Sample response

On success: HTTP Code 200

{“result”:true, “timestamp”:1672531200, “list”:[<array>]}

On error: HTTP Code 401

{“result”:false, ”error”:"Unauthorized."}

The “list” in the returned result is an array, and each array element has the following format:

    “rid”: 12345
    “fixture”: “Example Fixture”
    “manufacturer”: “Example Manufacturer"
    “revision”: ”Example revision"
    “creationDate”: “1570494396”
    “lastModified”:  ”1570494396”,
    “uploader”: “Manuf.”
    “rating: “4.1”
    “version: “1.0”
    “creator”: “Real User 42”
    “uuid”: “AAAAAAAA-3545-4C7C-ACA2-AAAAAAAAAAAA"
    “filesize”: 4809117
    “modes”: array
        {“0”: array [2] {name: “mode1”, dmxfootprint: 49 }}

Response definitions

The following table describes each item in the response.

Response itemDescriptionData type
ridRevision ID.Integer
fixtureFixture name.String
manufacturerManufacturer name.String
revisionRevision name.String
creationDateCreation date of the revision in UNIX timestamp format.Long
lastModifiedLast modification date of the revision in UNIX timestamp format.Long
uploaderUploader type: "Manuf." if the file was uploaded by a manufacturer, "User" if it was uploaded by a user.String
ratingRating of the revision, from 0 to 5.Float
versionGDTF version of the revision.String
creatorUsername of the original file uploader.String
uuidUnique ID of the fixture type. Each fixture has a unique ID that does not change across multiple revisions.String
filesizeFile size in bytes.Long
modesArray with the modes, each item contains the Mode name and the DMX footprint.Array

Each entry in the modes array contains the following items:

ItemDescriptionData type
nameMode name.String
dmxfootprintDMX footprint of the mode.Integer

File download

This function allows the download of a single file.



ridRequiredRevision ID as provided in the Get List function.Integer


For a successful download, the file is returned as a binary stream. For an error, a JSON object is returned. The HTTP status code can be used to determine if the download was successful or not, and the JSON response contains the relevant error message.

Content typeHTTP Status codes
application/octet-stream or application/json200, 400, 401, 500

Sample request

curl    -b session.txt
        --output file.gdtf

Sample response

On success: HTTP Code 200

File is downloaded to “file.gdtf”.

On error: HTTP Code 404

{“result”:false, ”error”:"File does not exist."}

Source of this documentation

Source on GitHub