/rput

The eas/rput endpoint is used to asynchronously upload files. Use /eas/put to synchronously upload files. A file can only be inserted if a filename is provided, either by setting it as query parameter or in the Content-Disposition header set by the web server of the URL.

POST /eas/rput

post

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

filenamestringOptional

The filename to store. The extension of the filename determines the routing for this file. It is the basis for the the permission check as well as the version production. If the filename is omitted, fylr will use the filename retrieved by the HEAD request which is performend to check the url. If skip_head_request is used, filename is mandatory.

leavebooleanOptional

If leave is set, the file will not be copied into the fylr storage. Use this to manage remote files which are not meant to be copied into fylr storage. Renditions for this file will still be produced by fylr.

version_namestringOptional

If a version name is given, the upload is meant to be a manual rendition. As such, the id_parents must be given alongside with it. The referenced parent files must be original and have set their produce_versions to false. Version names must be unique for all manually uploaded versions.

id_parentnumber · int64Optional

A parent id must be set for manual rendition uploads when using version_names. The id must point to a file "original".

referencestringOptional

A unique file reference to identify the file. It can be used in file lookups when linking files to objects.

skip_duplicate_referencebooleanOptional

If set, this setting avoids unique constraints error from duplicate reference. Instead, if a duplicate is encountered the response loads the exsting file and marks it notes that in _duplicates.

If /rput/bulk is used and the request contains a new file and duplicates of it, all files will be carray the _duplicates marker in the response.

custom_produce_configstring · jsonOptional

Custom produce config is explained in POST /api/v1/eas/{fileId}.

prioritynumber · int64Optional

When adding the renditions job to the file worker queue a priority is used. Set 2 for interactive, 4 for highest and 0 for normal.

Default: 0

produce_versionsbooleanOptional

If set to true, fylr produces renditions for each file uploaded, if set to false, no versions are produced. If no values is given (no parameter set or less values than needed), true is assumed.

Default: true

generate_metadatabooleanOptional

If set to false, metadata for this file can be provived in the request body. This is only allowed if leave is set to true and produce_versions to false. This is used by fylr restore for the fastest mode to (test-)import files from another system.

Default: true

urlstring · urlRequired

The URL to copy the file from. fylr is trying to connect to the URL using a HEAD request. If a non 200 response is received from that request, a GET request is performed (without reading the body). If no filename is given, the request is used to determine the filename. If a filename without an extension is given, the request is used to determine the extension. If a filename in the Content-Disposition header is found, fylr used that. If not, the last part of the URL is used to derive a filename. If that name has no extension, fylr parses the Content-Type header to determine a file extension from the provided MIME type. The Content-Type header also sets the MIME type of the file in the database. The Content-Length header is used to set the filesize of the file. If leave is set, the Content-Length header with a filesize > 0 is required. If leave is not set, the Content-Length header can be missing. If it is there, it needs to be > 0 too. The host portion of the URL is validated against the fylr.eas.rput.blockedHosts config before any outbound request is made. If the host (or any address it resolves to) matches an entry, the call is refused with a 400 error. The compiled-in default blocks loopback, link-local and private (RFC1918 / ULA) ranges; fylr's own internal services (backend callback URL, Elasticsearch nodes, execservers, backend / execserver listener addresses) are added automatically on their exact host:port. See fylr.example.yml for the entry syntax (IP / CIDR / hostname / single-label wildcard, optional :port) and how to override the list.

skip_head_requestbooleanOptional

If set, fylr does not check the validity of the URL by performing the HEAD request to the remote server. If set, providing a filename is required. This can be used to speed up file imports.

Body

application/json

Free-form file metadata document — a map of metadata groups to per-group key/value bags.

The well-known group _technical_metadata carries the file's intrinsic properties (width, height, dpi, ...); other groups carry whatever the configured metadata recipes produce (EXIF, IPTC, XMP, custom extractors). Group names beginning with _ are reserved for fylr-managed groups; user-defined groups should use unprefixed names.

Each group's value is a flat key/value bag whose values can be strings, numbers, booleans, nested objects, or arrays — the type set per key is fixed by the producing recipe, not by fylr.

Responses

200

The file was registered with fylr. The response carries the file descriptor in long format.

application/json

_idnumber · int64 · min: 1Optional

The _id is created when a file is uploaded into the fylr server.

eas_parent_idnumber · int64 · nullableOptional

The eas_parent_id is the id of the file this file is derived from. When using /api/produce, the newly produced files will get the parent id set to the file they are produced from.

referencestring · nullableOptional

If set, this reference string is a unique string identifying the file. If the reference contains a sha244:<hash> or sha256:<hash>, the provided hash can be checked against the file's checksum using an action triggerable in /inspect/files. Other parts of the reference can be added but must be separated by :.

date_uploadedstring · timestampOptional

The UTC timestamp when this file was uploaded.

best_datestring · timestampOptional

Best date is a compiled UTC timestamp from the technical metadata. fylr uses the first set date from technical_metadata.date_time_original, technical_metadata.create_date, date_uploaded.

filesizenumber · int64Optional

The file size in bytes.

statusstringOptional

The status of the file. Known states are: pending, processing, sync, done, failed. Files and renditions can be accessed in status sync and done. Only files in state done can be exported.

last_status_atstring · timestampOptional

The UTC timestamp when the last status change was last written to the database.

extensionstringOptional

The compiled extension of the file. This is matched by parsing available recipes at the time of the metadata generation. Extensions are matched by longer length first. So for a file flower.webdvd.zip the extension matched would be .webdvd.zip and not .zip if there is an available recipe.

classstringOptional

The compiled class of the file. The classes are set by the recipe. Standard recipes of fylr include image, audio, office, video. The fylr frontend uses the class to pick the general player to view the file. A class unknown is assigned if no matching recipe was found but the upload accepts unknown types.

class_version_statusstringOptional

A compiled concatenation of class, version and status, joined by .. This is used for aggregations of file status.

class_extensionstringOptional

A compiled concatenation of class, version, joined by .. This is used for aggregations of files

is_originalbooleanOptional

Set to true if the file is an original. It is false if the file is a generated or uploaded rendition. Produced files are registered as originals underneath the original they are produced from.

hashstringOptional

The hash is a non unique identifier of the file. For remote files, it is the md5sum of the URL, for local files it is the SHA-256 of the binary file data. It is calculated together with the metadata for the file and a copy of technical_metadata.sha256_hash. The hash is used for duplicate detection.

compiledstringOptional

A compiled version of the metadata for this file. For images this looks like this: JPG, 1920 x 1285 px, 569.5 kB.

original_filepathstringOptional

Filename of the file as set during the upload. On Windows, this can contain drive letters and backslashes.

original_filenamestringOptional

The filename as set by original_filepath minus the path.

original_filename_basenamestringOptional

The filename as set by original_filepath minus the path and the detected extension.

preferredbooleanOptional

This may be set if the file is in the context of an object. If set, preferred indicates that this version is the preferred one in a list of other versions.

namestringOptional

Custom name of the file. This is set in the relation to the object. When retrieving the file via /api/eas.

400

The remote upload could not be processed. The code field identifies the specific reason — typically EasInvalidURL for a missing or unparseable url, EasEmptyFilename / EasInvalidFilename (filename validation), or EasRputError when the upstream URL is blocked by the SSRF list or is otherwise unreachable. ReadOnlyMode is returned if the instance is in read-only mode.

application/json

401

No authenticated user (UserRequired). The upload-right check runs before the remote URL is fetched, so an anonymous request is rejected here.

application/json

403

The authenticated user holds no RIGHT_ASSET_UPLOAD anywhere (and is neither system root nor system.poolmanager). The code is RightRequired.

application/json

[
  {
    "_id": 1,
    "eas_parent_id": 1,
    "reference": "text",
    "upload_user": {
      "_basetype": "user",
      "user": {}
    },
    "date_uploaded": "text",
    "best_date": "text",
    "filesize": 1,
    "status": "text",
    "last_status_at": "text",
    "extension": "text",
    "class": "text",
    "class_version_status": "text",
    "class_extension": "text",
    "is_original": true,
    "hash": "text",
    "technical_metadata": {
      "width": 1920,
      "height": 1440,
      "dpi": 1,
      "colorspace": "rgb",
      "format": "landscape",
      "mime_type": "image/jpeg",
      "file_type_extension": "jpg",
      "filesize": 885714,
      "dimensions": {
        "width": 1920,
        "height": 1440,
        "unit": "px"
      },
      "sha256_hash": "2f19a9fd4ad56217899e275c0177a14e40a3061cc96ea0747ce973877aead14c",
      "huhu": {
        "gut": "sieht torsten custom:und henk"
      }
    },
    "compiled": "text",
    "compiled_props": {
      "extension": "text",
      "dimensions": "text",
      "duration": "text",
      "pages": "text"
    },
    "_mapped_metadata": {
      "_objecttype": "text",
      "_mask": "text",
      "_system_object_id": 1,
      "_global_object_id": "text",
      "_uuid": "text",
      "_owner": {
        "_basetype": "user",
        "_owner": true,
        "_pool_contact": true,
        "user": {
          "_id": 1,
          "lookup:_id": {
            "reference": "text"
          },
          "_generated_displayname": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "group": {
          "_id": 1,
          "lookup:_id": {
            "reference": "text"
          },
          "_generated_displayname": "text"
        }
      },
      "_created": "text",
      "{objecttype}": {
        "_id": 1,
        "_version": 1,
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "metadata": {
      "groupnames": [
        "text"
      ],
      "groups": {
        "ANY_ADDITIONAL_PROPERTY": [
          {
            "value": null,
            "print": "text",
            "name": "text",
            "group": "text"
          }
        ]
      }
    },
    "original_filepath": "text",
    "original_filename": "text",
    "original_filename_basename": "text",
    "versions": {
      "ANY_ADDITIONAL_PROPERTY": {
        "_id": "text",
        "aspect_ratio": "text",
        "blurhash": "text",
        "class": "text",
        "class_extension": "text",
        "date_created": "text",
        "_download_allowed": true,
        "_show_allowed": true,
        "dpi": "text",
        "extension": "text",
        "filesize": "text",
        "hash": "text",
        "height": "text",
        "last_status_at": "text",
        "orientation": "text",
        "percent_done": "text",
        "status": "text",
        "url": "text",
        "zoom_url": "text",
        "iiif_url": "text",
        "deep_link_url": "text",
        "watermark": "text",
        "width": "text",
        "path": "text",
        "technical_metadata": "text"
      }
    },
    "_duplicates": [
      {
        "_id": 1,
        "certainty": 1,
        "linked_system_objects": [
          {
            "_system_object_id": 1,
            "_column_id": 1
          }
        ]
      }
    ],
    "_linked_objects": [
      {
        "_system_object_id": 1,
        "_version": 1
      }
    ],
    "preferred": true,
    "name": "text",
    "frontend_prefs": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "lookup:_id": {
      "reference": "text"
    }
  }
]