Introduction
Guides
API Reference
SPI CRM v2
SPI CRM v1
SPI Digital Receipts
SPI Discount Cards
SPI Events
SPI Gift Card
SPI Insurance
SPI Payment
SPI Product Recommendations
SPI Product Search
SPI RFID
SPI Tax Free
Journals v3
Media Object Storage
Purchase Prices v3
Shipments v3

Media Object Storage API

Generate upload URL

post /v1/media/upload-url

Generate a pre-signed URL for direct file upload to S3. All processed images and thumbnails are converted to JPEG format regardless of input format.

REQUEST BODY
object
UploadUrlRequest
Returns

Pre-signed upload URL generated successfully

UploadUrlResponse
post/v1/media/upload-url
HTTP Status Code Summary
200Pre-signed upload URL generated successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
500Internal server error

Get file metadata

get /v1/media/{file_id}

Retrieve metadata for a specific file.

PARAMETERS
file_id
string
path
REQUIRED

File identifier

Returns

File metadata retrieved successfully

FileMetadataResponse
get/v1/media/{file_id}
HTTP Status Code Summary
200File metadata retrieved successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
500Internal server error

Search files

get /v1/media/search

Search for files by entity type and ID with pagination support.

PARAMETERS
entity_type
string
query
REQUIRED

Filter by entity type

Available values:
  • shipment_item
entity_id
string
query
REQUIRED

Entity identifier, there are different formats for each entityType

  • shipment_item: shipment_id|sku|reason_code|discrepancy_id
    • Examples:
      • "1RT823V93|SKU-001|DAMAGED|51076f94-b531-483c-884b-35ad67afa113"
      • "EC9UNVLDH|PROD-123|SHORTAGE|f2a18161-c2d4-4834-9133-2466c9b702ad"
limit
number
query

Maximum number of results per page

Default: 50
cursor
string
query

Pagination cursor from previous response

Returns

Files retrieved successfully

FileSearchResponse
get/v1/media/search
HTTP Status Code Summary
200Files retrieved successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
500Internal server error

Objects

UploadUrlResponse
object

PROPERTIES
file_id
string
(uuid)
READ ONLY
REQUIRED

Unique file identifier

Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
upload_url
string
(uri)
READ ONLY
REQUIRED

Pre-signed upload URL

Example: "https://media-bucket.s3.amazonaws.com/uploads/f47ac10b-58cc-4372-a567-0e02b2c3d479?X-Amz-Algorithm=..."
fields
object
READ ONLY
REQUIRED

Additional form fields required for upload. See the AWS documentation for more details

Example: { "Content-Type": "image/jpeg", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "X-Amz-Credential": "ASIAUBGXXXXXXXX/20250820/eu-north-1/s3/aws4_request" }
<*>
string
Example: { "Content-Type": "image/jpeg", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "X-Amz-Credential": "ASIAUBGXXXXXXXX/20250820/eu-north-1/s3/aws4_request" }
expires_at
integer
READ ONLY
REQUIRED

Upload URL expiration time, UNIX timestamp in seconds

Example: 1736522400

Error
object

PROPERTIES
error_code
string
REQUIRED
error_data
REQUIRED
message
string
REQUIRED
request_id
string
REQUIRED
<*>
object
Example: { "error_code": "INVALID_REQUEST", "error_data": { "message": "Invalid request parameters" }, "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }

UploadUrlRequest
object

PROPERTIES
file_name
string
REQUIRED

Original filename with extension

Example: "product-image-001.jpg"
Min Length: 1
content_type
string
REQUIRED

MIME type of the file

Example: "image/jpeg"
VALUES
image/jpeg
image/png
image/webp
image/gif
entity_type
string
REQUIRED

Entity type for logical file grouping

Example: "shipment_item"
VALUES
shipment_item
entity_id
string
REQUIRED

Entity identifier, there are different formats for each entityType

  • shipment_item: shipment_id|sku|reason_code|discrepancy_id
    • Examples:
      • "1RT823V93|SKU-001|DAMAGED|51076f94-b531-483c-884b-35ad67afa113"
      • "EC9UNVLDH|PROD-123|SHORTAGE|f2a18161-c2d4-4834-9133-2466c9b702ad"
Example: "1RT823V93|SKU-001|DAMAGED|51076f94-b531-483c-884b-35ad67afa113"
<*>
object

FileMetadataResponse
object

Information about a file

PROPERTIES
file_id
string
(uuid)
READ ONLY
REQUIRED

Unique file identifier

Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
content_type
string
READ ONLY
REQUIRED

MIME type of the file

Example: "image/jpeg"
VALUES
image/jpeg
image/png
image/webp
image/gif
file_size
integer
READ ONLY
REQUIRED

File size in bytes

Example: 2048576
Minimum: 0
entity_type
string
READ ONLY
REQUIRED

Entity type for logical grouping

Example: "shipment_item"
VALUES
shipment_item
entity_id
string
READ ONLY
REQUIRED

Entity identifier, there are different formats for each entityType

  • shipment_item: shipment_id|sku|reason_code|discrepancy_id
    • Examples:
      • "1RT823V93|SKU-001|DAMAGED|51076f94-b531-483c-884b-35ad67afa113"
      • "EC9UNVLDH|PROD-123|SHORTAGE|f2a18161-c2d4-4834-9133-2466c9b702ad"
Example: "1RT823V93|SKU-001|DAMAGED|51076f94-b531-483c-884b-35ad67afa113"
status
string
READ ONLY
REQUIRED

File processing status

Example: "ready"
VALUES
uploading
uploaded
processing
ready
failed
created_at
integer
READ ONLY
REQUIRED

File metadata creation, UNIX timestamp in seconds

Example: 1673369400
updated_at
integer
READ ONLY
REQUIRED

File metadata last updated, UNIX timestamp in seconds

Example: 1673369400
download_url
string
(uri)
READ ONLY

Pre-signed download URL (only present when status is 'ready')

Example: "https://d123456789.cloudfront.net/uploads/f47ac10b-58cc-4372-a567-0e02b2c3d479?Expires=..."
download_expires_at
integer
READ ONLY

Download URL expiration time, UNIX timestamp in seconds (only present when download_url is provided)

Example: 1673369400
thumbnail_url
string
(uri)
READ ONLY

Pre-signed thumbnail download URL (only present for supported image files when thumbnail exists)

Example: "https://d123456789.cloudfront.net/uploads/f47ac10b-58cc-4372-a567-0e02b2c3d479-thumb.jpg?Expires=..."
thumbnail_expires_at
integer
READ ONLY

Thumbnail URL expiration time, UNIX timestamp in seconds (only present when thumbnail_url is provided)

Example: 1673369400

FileSearchResponse
object

A paginated response containing file metadata

PROPERTIES
files
array
(FileMetadataResponse)
READ ONLY
REQUIRED

Array of file metadata objects

cursor
string
nullable
READ ONLY

Pagination cursor for next page

Example: "eyJmaWxlSWQiOiJmNDdhYzEwYi01OGNjLTQzNzIifQ=="
Copyright © 2026 Sitoo AB. All rights reserved.