Skip to main content

Upload file

The Gateway provides an endpoint to upload files. You can either upload a file or via an external URL.

note

From the middle of the year, it will also be possible to upload images directly when creating an entity.

Request​

POST 
/api/v1/entities/:id/file

Content-Type: multipart/form-data

{
  "file": "binary",
  "url": "URL-string",
  "definition": "{'name': 'Test', 'identifier': 'test', 'fileUsage': ['gallery', 'thumbnail']}"
}

File (file)​

The file that should be uploaded.

URL (url)​

Alternatively, you can provide a URL to the file that should be uploaded.

Definition (definition)​

The definition object contains the definition of the file.

  • name: string
    The name the file should have in the database.
  • fileUsage: string array
    The file Usage defines how the file should be used. Multiple values are possible.
    • logo - The image should be used as a logo
    • gallery - The image should be used in a gallery
    • thumbnail - The image should be used as a thumbnail
    • equirectangular_image - The image should be displayed as 360° image. Of course does this only work if the image is an equirectangular image.
    • download - The image should be available for download
  • duplicateStrategy: string
    Defines what should happen if the file already exists.
    • return - Return the existing file if it already exists, otherwise upload. This does not modify the existing file!
    • overwrite - Overwrite the file if it already exists. The file name must be the same as the existing file.

Response​

The Gateway will respond with the uploaded file.

{
  "reference": "test",
  "file": {
        "reference": "67aa15cff2164c1316a3675f",
        "name": "test.jpeg",
        "type": "IMAGE",
        "mimeType": "image/jpeg",
        "colorProfile": "RGB",
        "urls": [
            {
                "type": "thumbnail",
                "src": "https://media.venus.bayern/social/prod/67aa15cff2164c1316a3675f/thumbnail/test.jpeg"
            },
            {
                "type": "gallery",
                "src": "https://media.venus.bayern/social/prod/67aa15cff2164c1316a3675f/gallery/test.jpeg"
            }
        ],
        "size": 18812,
        "createdAt": "2025-02-10T15:05:51.149+00:00",
        "updatedAt": "2025-02-10T15:05:51.149+00:00",
        "metadata": {
            "tiff": {
                "YResolution": [],
                "XResolution": "1/1",
                "YCbCrSubSampling": [
                    "2",
                    "2"
                ],
                "ImageWidth": "300",
                "ImageLength": "168",
                "ResolutionUnit": "1",
                "BitsPerSample": [
                    "8"
                ]
            }
        },
        "fileUsage": ["gallery", "thumbnail"]
    }
}

Reference (reference)​

This is the identifier we previously defined in the definition object.

File (file)​

This object contains the uploaded file.