Files & Uploads Endpoints

File upload via presigned URLs, file serving, and admin operations.

---

Presigned URL Upload

Method	Endpoint	Description
POST	/api/v1/uploads/presigned-url	Generate a presigned URL for direct R2 upload

Request

Field	Type	Required	Description
filename	string	Yes	Original filename
content_type	string	Yes	MIME type of the file
size	integer	No	File size in bytes (used for dynamic token expiration)

Response

Field	Type	Description
upload_url	string	Presigned R2 URL — client PUTs file directly here
file_url	string	CDN URL where the file will be accessible
upload_method	string	PUT
expires_in_seconds	integer	Token validity (default 15 min, adjusted by file size)
max_file_size	integer	Maximum allowed file size in bytes (52428800 = 50MB)

The client uploads the file directly to R2 using the presigned URL. The file is stored at temp/{file_id}_{timestamp}_{safe_filename} and later relocated to permanent storage during entity creation.

MediaResource Lifecycle

The file_url returned from the presigned response is a temporary CDN path pointing to the temp/ prefix. When the entity is created (e.g., POST /products), the Backend's MediaResourceService.ingest_all() processes the temp URL:

1. HEAD the temp file to get ETag and size
2. Compute content hash for deduplication
3. On dedup miss: create MediaResource, relocate file to canonical path media/{resource_id}/file.{ext}
4. On dedup hit: reuse existing MediaResource, delete temp file
5. Create MediaResourceAttachment linking the resource to the entity

The final canonical URL is {CDN_URL}/media/{resource_id}/file.{ext}. See MediaResource Lifecycle for full details.

---

File Serving

Method	Endpoint	Description
GET	/files/{file_path:path}	Backward compatibility endpoint to serve a file via 302 redirect to CDN/MinIO

Query Parameters

Parameter	Type	Description
type	string	Optional format conversion (webp, jpeg, png, avif, gif)

Behavior

• In production (Cloudflare Image Transformations enabled): redirects to /cdn-cgi/image/format={type},quality=90/{file_path}
• In development (MinIO): redirects directly to {R2_PUBLIC_URL}/{file_path}

---

Admin Upload [ Deprecated, needs removal ]

Method	Endpoint	Description
POST	/api/v1/uploads/admin/upload-lora	Upload a LoRA model file (superuser only)

Requires superuser authentication. Used for uploading LoRA training model files to storage.

---

Validation Rules

Rule	Value
Max file size	50MB
Allowed image types	image/jpeg, image/png, image/webp, image/gif, image/avif
Other allowed types	application/zip, application/pdf, video/mp4, audio/mpeg
Filename sanitization	Directory traversal prevention, safe character enforcement

---

Bulk Upload

Method	Endpoint	Description
POST	/bulk-upload/	Start a bulk CSV import
GET	/bulk-upload/{id}	Get bulk upload job status
GET	/bulk-upload/{id}/errors	Get upload errors for a job

---

Export Configuration

Method	Endpoint	Description
GET	/export-configuration/	List export configurations
POST	/export-configuration/	Create an export configuration

---

API Reference

Sartiq Backend Server - Files 0.1.0

export-configuration

---

GET /api/v1/users/me/export-configuration

Get My Export Configuration

Description

Get the current user's export configuration.

Returns the user's configured image format and metadata adapter settings. Returns 404 if the user hasn't created an export configuration yet.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Responses

200 OK

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

---

POST /api/v1/users/me/export-configuration

Create My Export Configuration

Description

Create an export configuration for the current user.

Allows users to specify their preferred image format and metadata adapter. Returns 400 if the user already has an export configuration.

Example request body:

{
    "metadata_adapter": "ovs",
    "image_format": "jpeg"
}

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

application/json

{
    "image_format": "webp",
    "metadata_adapter": "default"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter",
            "default": "default"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat",
            "default": "webp"
        }
    },
    "type": "object",
    "title": "ExportConfigurationCreate",
    "description": "Schema for creating a new export configuration.\n\nUsed in POST requests to create user-specific export settings.",
    "example": {
        "image_format": "webp",
        "metadata_adapter": "default"
    }
}

Responses

201 Created422 Unprocessable Entity

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

DELETE /api/v1/users/me/export-configuration

Delete My Export Configuration

Description

Delete the current user's export configuration.

After deletion, images will be exported using system defaults (WebP format, no metadata injection). Returns 404 if no configuration exists.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Responses

204 No Content

---

PATCH /api/v1/users/me/export-configuration

Update My Export Configuration

Description

Update the current user's export configuration.

Allows partial updates - only provided fields will be updated. Returns 404 if the user hasn't created an export configuration yet.

Example request body (update only format):

{
    "image_format": "png"
}

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

application/json

{
    "image_format": "jpeg",
    "metadata_adapter": "ovs"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "metadata_adapter": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/MetadataAdapter"
                },
                {
                    "type": "null"
                }
            ]
        },
        "image_format": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ImageFormat"
                },
                {
                    "type": "null"
                }
            ]
        }
    },
    "type": "object",
    "title": "ExportConfigurationUpdate",
    "description": "Schema for updating an existing export configuration.\n\nAll fields are optional to support partial updates via PATCH requests.",
    "example": {
        "image_format": "jpeg",
        "metadata_adapter": "ovs"
    }
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/users/{user_id}/export-configuration

Get User Export Configuration

Description

Get export configuration for a specific user.

Regular users can only access their own configuration. Admins can access any user's configuration.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
user_id	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/users/{user_id}/export-configuration

Create User Export Configuration

Description

Create export configuration for a specific user.

Regular users can only create their own configuration. Admins can create configuration for any user.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
user_id	path	string		No

Request body

application/json

{
    "image_format": "webp",
    "metadata_adapter": "default"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter",
            "default": "default"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat",
            "default": "webp"
        }
    },
    "type": "object",
    "title": "ExportConfigurationCreate",
    "description": "Schema for creating a new export configuration.\n\nUsed in POST requests to create user-specific export settings.",
    "example": {
        "image_format": "webp",
        "metadata_adapter": "default"
    }
}

Responses

201 Created422 Unprocessable Entity

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

PATCH /api/v1/users/{user_id}/export-configuration

Update User Export Configuration

Description

Update export configuration for a specific user.

Regular users can only update their own configuration. Admins can update configuration for any user.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
user_id	path	string		No

Request body

application/json

{
    "image_format": "jpeg",
    "metadata_adapter": "ovs"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "metadata_adapter": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/MetadataAdapter"
                },
                {
                    "type": "null"
                }
            ]
        },
        "image_format": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ImageFormat"
                },
                {
                    "type": "null"
                }
            ]
        }
    },
    "type": "object",
    "title": "ExportConfigurationUpdate",
    "description": "Schema for updating an existing export configuration.\n\nAll fields are optional to support partial updates via PATCH requests.",
    "example": {
        "image_format": "jpeg",
        "metadata_adapter": "ovs"
    }
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

DELETE /api/v1/users/{user_id}/export-configuration

Delete User Export Configuration

Description

Delete export configuration for a specific user.

Regular users can only delete their own configuration. Admins can delete configuration for any user.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
user_id	path	string		No

Responses

204 No Content422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/users/organizations/{org_id}/export-configuration

Get Organization Export Configuration

Description

Get organization's export configuration.

Organization members can view the shared export configuration. Returns 404 if no organization-level configuration exists.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
org_id	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/users/organizations/{org_id}/export-configuration

Create Organization Export Configuration

Description

Create export configuration for an organization.

Creates a shared export configuration that applies to all organization members. Returns 400 if the organization already has a configuration.

Example request body:

{
    "metadata_adapter": "ovs",
    "image_format": "jpeg"
}

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
org_id	path	string		No

Request body

application/json

{
    "image_format": "webp",
    "metadata_adapter": "default"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter",
            "default": "default"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat",
            "default": "webp"
        }
    },
    "type": "object",
    "title": "ExportConfigurationCreate",
    "description": "Schema for creating a new export configuration.\n\nUsed in POST requests to create user-specific export settings.",
    "example": {
        "image_format": "webp",
        "metadata_adapter": "default"
    }
}

Responses

201 Created422 Unprocessable Entity

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

PATCH /api/v1/users/organizations/{org_id}/export-configuration

Update Organization Export Configuration

Description

Update organization's export configuration.

Organization members can update the shared export configuration. Returns 404 if no configuration exists.

Example request body (update only format):

{
    "image_format": "png"
}

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
org_id	path	string		No

Request body

application/json

{
    "image_format": "jpeg",
    "metadata_adapter": "ovs"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "metadata_adapter": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/MetadataAdapter"
                },
                {
                    "type": "null"
                }
            ]
        },
        "image_format": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ImageFormat"
                },
                {
                    "type": "null"
                }
            ]
        }
    },
    "type": "object",
    "title": "ExportConfigurationUpdate",
    "description": "Schema for updating an existing export configuration.\n\nAll fields are optional to support partial updates via PATCH requests.",
    "example": {
        "image_format": "jpeg",
        "metadata_adapter": "ovs"
    }
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "image_format": "webp",
    "metadata_adapter": "default",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "metadata_adapter": {
            "$ref": "#/components/schemas/MetadataAdapter"
        },
        "image_format": {
            "$ref": "#/components/schemas/ImageFormat"
        }
    },
    "type": "object",
    "required": [
        "id",
        "user_id",
        "metadata_adapter",
        "image_format"
    ],
    "title": "ExportConfigurationPublic",
    "description": "Public schema for export configuration responses.\n\nSupports both user-level and organization-level configurations.\n- Personal configs have organization_id = None\n- Organization configs have organization_id set\n\nIncludes all fields plus timestamps from BaseModel.\nUsed in GET responses and after successful create/update operations.",
    "example": {
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "image_format": "webp",
        "metadata_adapter": "default",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

DELETE /api/v1/users/organizations/{org_id}/export-configuration

Delete Organization Export Configuration

Description

Delete organization's export configuration.

After deletion, organization products will use individual user configurations or system defaults. Organization members can delete the configuration.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
org_id	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "message": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "message": {
            "type": "string",
            "title": "Message"
        }
    },
    "type": "object",
    "required": [
        "message"
    ],
    "title": "Message"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

uploads

---

POST /api/v1/uploads/presigned-url

Get Presigned Url

Description

Generate presigned URL for file upload. In local implementation, returns a token and upload endpoint instead.

Requires authentication.

Enhanced features: - Dynamic token expiration based on file size - Better content type validation - File size limits for < 10MB files

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

application/json

{
    "folder": "string",
    "filename": "string",
    "content_type": "string",
    "file_size": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "folder": {
            "type": "string",
            "title": "Folder"
        },
        "filename": {
            "type": "string",
            "title": "Filename"
        },
        "content_type": {
            "type": "string",
            "title": "Content Type"
        },
        "file_size": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "File Size"
        }
    },
    "type": "object",
    "required": [
        "folder",
        "filename",
        "content_type"
    ],
    "title": "PresignedUrlRequest"
}

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/uploads/admin/upload-lora

Upload Subject Lora

Description

Upload a LoRA file for a subject to the compute server. File must be a supported LoRA format (.safetensors, .ckpt, .pt, .pth, .bin) and max 100MB. Optionally set or update the lora_trigger (trigger word) for the subject.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

multipart/form-data

{
    "file": "string",
    "lora_trigger": null,
    "entity_type": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "file": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "title": "File"
        },
        "lora_trigger": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Lora Trigger"
        },
        "entity_type": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Entity Type"
        }
    },
    "type": "object",
    "required": [
        "file"
    ],
    "title": "Body_upload_lora"
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "file_path": null,
    "partial_path": null,
    "filename": null,
    "file_size": null,
    "upload_timestamp": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "file_path": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "File Path"
        },
        "partial_path": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Partial Path"
        },
        "filename": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Filename"
        },
        "file_size": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "File Size"
        },
        "upload_timestamp": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Upload Timestamp"
        }
    },
    "type": "object",
    "required": [
        "file_path",
        "partial_path",
        "filename",
        "file_size",
        "upload_timestamp"
    ],
    "title": "LoraUploadResponse"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

bulk-upload

---

POST /api/v1/products/bulk-upload/

Create Bulk Upload Task

Description

Create a new bulk upload task and start processing the ZIP file.

The ZIP file should contain: - A CSV file with product metadata - Folders for each product, named with the product SKU - Each product folder should contain a cover image and optional additional images

If shooting_id is provided, the products will be integrated with the shooting.

Additional options: - caption_products: Whether to generate AI captions for the products (default: True) - skip_existing_skus: Whether to skip products with SKUs that already exist (default: False)

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
caption_products	query	boolean	True	No
shooting_id	query			No
skip_existing_skus	query	boolean	False	No

Request body

multipart/form-data

{
    "file": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "file": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "title": "File"
        }
    },
    "type": "object",
    "required": [
        "file"
    ],
    "title": "Body_create_bulk_upload_task"
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "owner_id": "0c3b1c40-ee1b-45e6-a01e-c3c1a4378714",
    "id": "5dc12c25-6b16-4f85-9d0e-f057cb8ca81f",
    "created_at": "2022-04-13T15:42:05.901Z",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "filename": "string",
    "status": "PENDING",
    "file_url": null,
    "total_products": 0,
    "processed_products": 0,
    "successful_products": 0,
    "failed_products": 0,
    "skipped_products": 0,
    "results": {},
    "error_message": null,
    "shooting_id": null,
    "completed_at": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "owner_id": {
            "type": "string",
            "format": "uuid",
            "title": "Owner Id"
        },
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "filename": {
            "type": "string",
            "maxLength": 255,
            "title": "Filename"
        },
        "status": {
            "$ref": "#/components/schemas/BulkUploadStatus",
            "default": "PENDING"
        },
        "file_url": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "File Url",
            "description": "URL of the stored ZIP file, used for background processing"
        },
        "total_products": {
            "type": "integer",
            "title": "Total Products",
            "default": 0
        },
        "processed_products": {
            "type": "integer",
            "title": "Processed Products",
            "default": 0
        },
        "successful_products": {
            "type": "integer",
            "title": "Successful Products",
            "default": 0
        },
        "failed_products": {
            "type": "integer",
            "title": "Failed Products",
            "default": 0
        },
        "skipped_products": {
            "type": "integer",
            "title": "Skipped Products",
            "default": 0
        },
        "results": {
            "additionalProperties": {
                "additionalProperties": true,
                "type": "object"
            },
            "type": "object",
            "title": "Results",
            "description": "Dictionary of product upload results by SKU"
        },
        "error_message": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Error Message"
        },
        "shooting_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Shooting Id"
        },
        "completed_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Completed At"
        }
    },
    "type": "object",
    "required": [
        "owner_id",
        "filename"
    ],
    "title": "BulkUploadTask",
    "description": "Represents a bulk upload task for processing multiple products from a ZIP file.\n\nTracks the status, progress, and results of the upload process."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/products/bulk-upload/

List Bulk Upload Tasks

Description

List bulk upload tasks for the current user.

Optionally filter by status.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
limit	query	integer	100	No
skip	query	integer	0	No
status	query			No

Responses

200 OK422 Unprocessable Entity

application/json

[
    {
        "owner_id": "b39f128e-a7fd-4685-b61a-0ea5abf4b701",
        "id": "24d87810-d122-4621-a3b8-bcc40b8a8e72",
        "created_at": "2022-04-13T15:42:05.901Z",
        "updated_at": "2022-04-13T15:42:05.901Z",
        "filename": "string",
        "status": "PENDING",
        "file_url": null,
        "total_products": 0,
        "processed_products": 0,
        "successful_products": 0,
        "failed_products": 0,
        "skipped_products": 0,
        "results": {},
        "error_message": null,
        "shooting_id": null,
        "completed_at": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/BulkUploadTask"
    },
    "title": "Response List Bulk Upload Tasks"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/products/bulk-upload/{task_id}

Get Bulk Upload Task

Description

Get a bulk upload task by ID.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
task_id	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "owner_id": "7d8bbb0c-2696-4044-8092-e247436c321b",
    "id": "7e6c5986-78d0-4e01-99e3-9a8befac2e8e",
    "created_at": "2022-04-13T15:42:05.901Z",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "filename": "string",
    "status": "PENDING",
    "file_url": null,
    "total_products": 0,
    "processed_products": 0,
    "successful_products": 0,
    "failed_products": 0,
    "skipped_products": 0,
    "results": {},
    "error_message": null,
    "shooting_id": null,
    "completed_at": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "owner_id": {
            "type": "string",
            "format": "uuid",
            "title": "Owner Id"
        },
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "filename": {
            "type": "string",
            "maxLength": 255,
            "title": "Filename"
        },
        "status": {
            "$ref": "#/components/schemas/BulkUploadStatus",
            "default": "PENDING"
        },
        "file_url": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "File Url",
            "description": "URL of the stored ZIP file, used for background processing"
        },
        "total_products": {
            "type": "integer",
            "title": "Total Products",
            "default": 0
        },
        "processed_products": {
            "type": "integer",
            "title": "Processed Products",
            "default": 0
        },
        "successful_products": {
            "type": "integer",
            "title": "Successful Products",
            "default": 0
        },
        "failed_products": {
            "type": "integer",
            "title": "Failed Products",
            "default": 0
        },
        "skipped_products": {
            "type": "integer",
            "title": "Skipped Products",
            "default": 0
        },
        "results": {
            "additionalProperties": {
                "additionalProperties": true,
                "type": "object"
            },
            "type": "object",
            "title": "Results",
            "description": "Dictionary of product upload results by SKU"
        },
        "error_message": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Error Message"
        },
        "shooting_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Shooting Id"
        },
        "completed_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Completed At"
        }
    },
    "type": "object",
    "required": [
        "owner_id",
        "filename"
    ],
    "title": "BulkUploadTask",
    "description": "Represents a bulk upload task for processing multiple products from a ZIP file.\n\nTracks the status, progress, and results of the upload process."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

files

---

GET /files/{file_path}

Serve File

Description

Serve files by redirecting to the storage backend (MinIO or Cloudflare R2 CDN).

In production with Cloudflare, uses Image Transformations for format conversion. In local dev (MinIO), redirects directly to the MinIO URL.

Input parameters

Parameter	In	Type	Default	Nullable	Description
file_path	path	string		No
type	query			No	Target image format

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

Schemas

Body_create_bulk_upload_task

Name	Type	Description
file	string

Body_upload_lora

Name	Type	Description
entity_type
file	string
lora_trigger

BulkUploadStatus

Type: string

BulkUploadTask

Name	Type	Description
completed_at
created_at	string(date-time)
error_message
failed_products	integer
file_url		URL of the stored ZIP file, used for background processing
filename	string
id	string(uuid)
owner_id	string(uuid)
processed_products	integer
results		Dictionary of product upload results by SKU
shooting_id
skipped_products	integer
status	BulkUploadStatus
successful_products	integer
total_products	integer
updated_at	string(date-time)

ExportConfigurationCreate

Name	Type	Description
image_format	ImageFormat
metadata_adapter	MetadataAdapter

ExportConfigurationPublic

Name	Type	Description
created_at	string(date-time)
id	string(uuid)
image_format	ImageFormat
metadata_adapter	MetadataAdapter
organization_id
updated_at	string(date-time)
user_id	string(uuid)

ExportConfigurationUpdate

Name	Type	Description
image_format
metadata_adapter

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

ImageFormat

Type: string

LoraUploadResponse

Name	Type	Description
file_path
file_size
filename
partial_path
upload_timestamp

Message

Name	Type	Description
message	string

MetadataAdapter

Type: string

PresignedUrlRequest

Name	Type	Description
content_type	string
file_size
filename	string
folder	string

ValidationError

Name	Type	Description
ctx
input
loc	Array<>
msg	string
type	string

Security schemes

Name	Type	Scheme	Description
OAuth2PasswordBearer	oauth2