How to Save Artifacts to S3 Storage Using Instant API

Overview

By default, Instant API (non-persistent mode) does not save any data anywhere – analysis results are returned immediately in the HTTP response, and nothing is stored. Starting from API 6.4.1, an optional feature allows saving analysis artifacts to external storage for debugging and incident investigation.

Instant API returns results to the client regardless of whether saving succeeds or fails – the saving process is isolated from the main analysis flow.

What gets saved

When enabled, the following artifacts are saved per analysis request into a folder identified by folder_id:

File	Naming pattern	Description
Container init data (for the container flow)	init_container.dat	Initial container data
Engine response	{source_media_id}_engine_response.json	Raw engine response (one file per analyzed media)
Request payload	payload.json	The original request body
API response	response.json	Full Instant API response (including image_b64 for best shot and, starting from 6.6.1, action shot)
<original_name>	No pattern	Original media file name

Invalid containers (those that fail validation) are also saved.

For Instant mode, original_url and thumb_url in the API response remain null even when saving is enabled. The saved data is a storage-only dump; there is no API endpoint to retrieve it.

Configuration

Enabling the feature

Saving is disabled by default. To enable it, set OZ_INSTANT_SAVING_ARTIFACTS_ENABLED to true (default: false). When enabled, artifacts are saved according to the OZ_FILE_STORAGE_TYPE value (LOCAL or S3), not exclusively to S3.

Storage type

Example (S3 storage):

OZ_FILE_STORAGE_TYPE: "S3"
OZ_LOCAL_STORAGE_SUPPORT_ENABLE: "true"
OZ_S3_STORAGE_SUPPORT_ENABLE: "true"

• OZ_FILE_STORAGE_TYPE – LOCAL or S3. Determines where artifacts are written.

• OZ_S3_STORAGE_SUPPORT_ENABLE – must be set to true for S3 to work; derived from OZ_FILE_STORAGE_TYPE.

• OZ_LOCAL_STORAGE_SUPPORT_ENABLE – enables local storage support. On SaaS, both local and S3 support are enabled simultaneously, so this should be set to true as well.

For proper configuration, depending on the installation method that you use, refer to the documentation provided with installation package.

S3 connection parameters

For OZ_FILE_STORAGE_TYPE=S3.

Required

Parameter	Description
OZ_STATIC_S3_BASE_URL	Base URL for constructing public links to static files
OZ_STATIC_S3_BUCKET	S3 bucket name
OZ_STATIC_S3_ENDPOINT_URL	S3 endpoint URL

Optional

Parameter	Description	Default
OZ_STATIC_S3_SUFFIX	Path prefix within the bucket	oz-media
OZ_STATIC_S3_BUCKET_URL	S3 bucket URL (can be left empty starting from 6.5.0)	""
OZ_STATIC_S3_ACCESS_KEY	S3 access key	None
OZ_STATIC_S3_SECRET_KEY	S3 secret key	None
OZ_STATIC_S3_REGION_NAME	AWS region name	None

Path formatting

• OZ_MEDIA_STATIC_FOLDER_FORMAT – strftime format for the date portion of the storage path (default: %Y/%m/%d/%H)

S3 bucket permissions

The following S3 actions are required for the IAM role or user accessing the bucket:

• s3:ListBucket (on the bucket resource)

• s3:GetObject (on objects within the bucket)

• s3:PutObject (on objects within the bucket)

• s3:DeleteObject (on objects within the bucket)

ListBucket is used during deletion: API lists all objects under the folder prefix, then deletes them individually. S3 has no native "delete folder" operation.

AWS IAM policy example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBucket",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
    },
    {
      "Sid": "ObjectOperations",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    }
  ]
}

Authorization impact

• OZ_AUTHORIZE_DISABLED_STATELESS – when true (typical for Instant), company_id in the storage path is set to 00000000-0000-0000-0000-000000000000. If false, company_id is taken from JWT.

Docker run example

sudo docker run -d -it \
  --name instant \
  -p 8081:8080 \
  -e OZ_INSTANT_SAVING_ARTIFACTS_ENABLED=true \
  -e OZ_STATIC_S3_SUFFIX=instant \
  -e OZ_STATIC_S3_BUCKET=<bucket> \
  -e OZ_STATIC_S3_ACCESS_KEY=<key> \
  -e OZ_STATIC_S3_SECRET_KEY=<secret> \
  -e OZ_STATIC_S3_ENDPOINT_URL=<endpoint_url> \
  -e OZ_STATIC_S3_BUCKET_URL=<bucket_url> \
  -e OZ_STATIC_S3_REGION_NAME=<region> \
  -e OZ_STATIC_S3_BASE_URL=<base_url> \
  -e OZ_FILE_STORAGE_TYPE=S3 \
  <api-instant-image>:<tag>

Storage path

s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/{company_id}/{OZ_MEDIA_STATIC_FOLDER_FORMAT}/{folder_id}/

Where:

• OZ_MEDIA_STATIC_FOLDER_FORMAT defaults to %Y/%m/%d/%H (e.g., 2025/12/18/09)

• company_id = 00000000-0000-0000-0000-000000000000. When authorization is enabled (OZ_AUTHORIZE_DISABLED_STATELESS=false), company_id is taken from the authenticated user's company.

Example: s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/00000000-0000-0000-0000-000000000000/2025/12/18/09/11111111-1111-1111-1111-111111111111/

Path format in Full API (for reference)

In Full API mode, the database stores the full S3 path including bucket and suffix:

s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/11111111-.../2026/04/09/09/.../media_id.jpeg

In the API response, s3:// is replaced with a public URL:

{PROTOCOL}://{API_HOSTNAME}/static/{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/...

For local storage, the replacement becomes {PROTOCOL}://{API_HOSTNAME}/static/.

Instant vs. Full API – comparison of storage behavior

Aspect	Instant API	Full API
Storage by default	Nothing is stored	All media and results stored in DB + file storage
Toggle required	Yes (OZ_INSTANT_SAVING_ARTIFACTS_ENABLED)	No (storage is a core function)
What is saved	media, payload, response, engine_response	media, analysis results, thumbnails, best shots, action shots
original_url in response	Always null	Public URL to static file
thumb_url in response	Always null	Public URL to thumbnail
DB records	None (stateless)	Full folder/media/analysis records
Storage path	s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/{company_id}/{OZ_MEDIA_STATIC_FOLDER_FORMAT}/{folder_id}/; not returned to the client	Stored in DB as s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/...; resolved to {PROTOCOL}://{API_HOSTNAME}/static/... in the response
Data deletion via API	Not applicable	DELETE /api/folders/{id} removes from DB and storage