close anchor

Files

To get information on files:

GET /files

Parameters

Param Type Description Optional
id string The UUID of an individual file.
editor string The UUID of an individual user by whom to filter entries based on their editorial purview (i.e., the privilege granted to editor-level users to edit or delete entries), as defined for the project.

If provided, this endpoint will deliver files including: those input by this user, those in group(s) linked to user group(s) in which this user exists (or in group(s) from which this user's not been excluded, depending on the editorial purview defined for the project), those identified with content entries for which this user is granted privilege, and those identified with the user directly (i.e., being linked to their profile via the /user/files endpoint).
user_input_by string The UUID of the primary user identified with a file, being the user who initially uploaded it, if known. Include an empty value to query files identified with no primary user.
user_index_of string The UUID of a user identified with files being linked to their profile via the /user/files endpoint.
ip_common boolean Indicate whether or not to query based on files being usable by everyone in the project. Include a value of either true or false to indicate the files to be provided.
group string Indicate, by providing a comma-delimited list, the UUID of file group(s) by which to be filter. Include a '+' prefix before this list of groups if a file is to be identified with every group declared (the default behavior of this endpoint is to provide files in any of the group(s) included), and prefix an individual group therein with '!' to exclude files linked to it.
type string Indicate, by providing a comma-delimited list, the IANA media type(s) by which to filter entries. The /file/types endpoint provides a list of known Elebase file types to include.
type_group string Indicate an Elebase file type group, being one of the values provided by the /file/type/groups endpoint, by which to filter entries.
text string Include text by which to filter entries. Input will be parsed for up to ten keywords and treated as a filter, in that only entries with keyword(s) present in the fields below will be included.
fields string Indicate, by providing a comma-delimited list, the field(s) in which to expect text keyword(s) be present. If a field includes localized text, only values in the endpoint transaction locale will be queried. If empty or not provided, each of these valid fields will be included: description, ip_attribution, name, title.
order string Indicate, by providing a comma-delimited list, the field(s) by which to order entries found. Include a '-' prefix if descending order is preferred in a given field ('+' is inferred by default). If empty or not provided, these valid fields will not be explicitly included: bytes, date_time.edit, date_time.init, id, name, ordinal.group, ordinal.user, title.

If either ordinal.group (dependent on the group parameter being included) or ordinal.user (based on user_index_of) is present in the field(s) to order by, this endpoint will deliver files in the preferred order indicated for that group, and/or by that user, if defined.

If plural locales indicated for the endpoint transaction and title is present in the list of field(s) to order by, querying will be performed in the initial locale (but data will be included for each).
page integer Identify the page on which to begin delivering entries. If not provided, the default value of 1 will be inferred.
limit integer Indicate a total of up to 100 entries to be delivered. If not provided, the default value of 10 will be inferred.
data string Indicate, by providing a comma-delimited list, the data field(s) to be delivered by this endpoint. If empty or not provided, this endpoint will include by default each of the data field(s) identified with the file object.

The data object provided by this endpoint includes both a total (integer) of entries found, and an index (array) of file object(s).

The Elebase Files API provides URL-based transformations for a variety of image and file types.

To post a file:

POST /files

In order to post a file, log a user in.

Parameters

Provide the input field(s) below as a JSON-encoded data object:

Param Type Description Optional
file object The file name and type, in which the name is that of the file itself (not a title) and its type is a known IANA media type.
text object The user-input title, description and ip_attribution of the file, each being provided in the endpoint transaction locale.
editable boolean Indicate whether or not this file is to be editable by users with editor-level privileges.
ip_verified boolean Indicate whether or not the user declares permission is granted to use this file.
ip_expiry string The date until which license or permission to use this file is valid, provided in ISO 8601 format.
ip_common boolean Indicate whether or not this file is to be usable by everyone in the project.
ip_note string Informational note on usage or license pertinent to this file.
locale string The locale identified with this file object, for example if an image with text is presented in English only.
point string The geographic point location to be identified with this file, being a comma-delimited textual value indicating both longitude and latitude, in that order.

The data object provided by this endpoint is the file object inserted to the project, in which the value for bytes will be either 0 or -1, and the initial url provided enables direct upload of the file itself before it expires, as in the PHP example below:

$curl = curl_init();

curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: '.$input->file['type']));
curl_setopt($curl, CURLOPT_INFILE, fopen($input->file['tmp_name'], 'rb'));
curl_setopt($curl, CURLOPT_INFILESIZE, filesize($input->file['tmp_name']));
curl_setopt($curl, CURLOPT_PUT, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 0);
curl_setopt($curl, CURLOPT_URL, $data->url);
curl_setopt($curl, CURLOPT_VERBOSE, false);

$obj = (object)array('body' => curl_exec($curl), 'info' => curl_getinfo($curl));

curl_close($curl);

print_r($obj);

If preferred, the jQuery below would be effectively identical:

$.ajax({
    complete: function(obj) {
        console.log(obj);
    },
    contentType: input.file.type,
    data: input.file,
    dataType: 'text',
    processData: false,
    type: 'PUT',
    url: data.url
});

Errors

If there is an endpoint transaction failure, or a problem with user input data, an error is provided:

ID/Type Description
invalid_date_time The ip_expiry provided is not a valid date.
invalid_file_name The file does not include a valid name.
invalid_file_type The file does not include a valid type.
invalid_geo_data_point The point is not a valid geographic location.
invalid_locale The locale is not valid or known on the Elebase platform.

If an error is not described on this page, the platform-wide error table provides further information.

To edit or update file info:

PUT /files

In order to update a file, log in the primary user identified with it (or a user with owner-level privileges) or, if its 'editable' preference is true, an editor-level user.

Parameters

Provide the input field(s) below as a JSON-encoded data object:

Param Type Description Optional
id string The UUID of the file object for which data is being updated.
text object The user-input title, description and ip_attribution of the file, each being provided in the endpoint transaction locale.
editable boolean Indicate whether or not this file is to be editable by users with editor-level privileges.
ip_verified boolean Indicate whether or not the user declares permission is granted to use this file.
ip_expiry string The date until which license or permission to use this file is valid, provided in ISO 8601 format.
ip_common boolean Indicate whether or not this file is to be usable by everyone in the project.
ip_note string Informational note on usage or license pertinent to this file.
locale string The locale identified with this file object, for example the language in which a video is presented.
point string The default geographic point location to be identified with this file, being a comma-delimited textual value indicating both longitude and latitude, in that order.
groups array The file group(s) in which this file is to exist, being a one-dimensional array in which each value is the UUID of an individual file group. In order to post a file to a group, log in a user with owner-level privileges or an editor in a user group linked to the file group in question.

The file will no longer be identified with groups not included in this transaction. In order to post a file to a group individually (not deleting it from other groups in which it'd previously been included), use the /file/groups endpoint instead.

The data object provided by this endpoint is the updated file object.

Errors

If there is an endpoint transaction failure, or a problem with user input data, an error is provided:

ID/Type Description
invalid_date_time The ip_expiry provided is not a valid date.
invalid_geo_data_point The point is not a valid geographic location.
invalid_locale The locale is not valid or known on the Elebase platform.

If an error is not described on this page, the platform-wide error table provides further information.

To delete a file:

DELETE /files

In order to delete a file, log in the user identified with the file (or a user with owner-level privileges).

Parameters

Param Type Description
id string The UUID of the file to be deleted.

The data object provided by this endpoint is the deleted file.

Register for an Invitation
Thank you!
We'll be in touch.
First Name*
Last Name*
(optional) Business Name
Role*
Email*