Integration Catalog

Endpoint ufficiali DAM ingest (clicca endpoint per specifiche)

Catalogo operativo per integrare qualsiasi form di upload (interno o esterno) via API DAM, con configurazione da control panel.

Endpoint Service Auth

POST/api/v1/dam/uploads/file/presign

Presign upload for a new asset

Allocate storage key + presigned URL for direct browser upload to Wasabi.

Param	In	Required	Description
`filename`	body	yes	Original file name.
`mime`	body	yes	Source MIME type.
`bytes`	body	no	Expected payload size in bytes.
`sha256`	body	no	Optional content hash for upload integrity.

Operational notes

Call before uploading binary data.
Use returned presigned URL to upload directly to Wasabi.
Pass returned storage key to commit endpoint.

cURL

curl -X POST '$BASE/api/v1/dam/uploads/file/presign' -H 'content-type: application/json' -d '{"filename":"hero.png","mime":"image/png"}'

polo-saas-api

session (oauth2-proxy headers)

POST/api/v1/dam/uploads/file

Commit upload for a new asset

Create asset + version record and enqueue async ingest pipeline.

Param	In	Required	Description
`external_storage_key`	body	yes	Wasabi key produced by presign.
`source_name`	body	yes	Original source file name.
`mime`	body	yes	Source MIME type.
`bytes`	body	yes	Uploaded byte size.
`ingest_profile_key`	body	no	Ingest profile key for preview policy.
`customer_key / project_key / subproject_key`	body	no	Routing metadata for DAM workflow.
`source_form / source_channel / source_url`	body	no	Source workflow metadata for traceability.

Operational notes

Call only after successful upload to Wasabi.
On success status starts from draft and moves through pipeline.
Current target status after ingest completion is ready_for_tagging.

cURL

curl -X POST '$BASE/api/v1/dam/uploads/file' -H 'content-type: application/json' -d '{"external_storage_key":"dam/AA000AA/AA000AA_v1_ab12cd.png","source_name":"hero.png","mime":"image/png","bytes":183921}'

polo-saas-api

session (oauth2-proxy headers)

POST/api/v1/dam/assets/:id/files/presign

Presign upload for new version on existing asset

Allocate upload slot for a new file/version under an existing asset.

Param	In	Required	Description
`id`	path	yes	Target asset id.
`filename`	body	yes	Incoming file name.
`mime`	body	yes	Incoming MIME type.
`version_index`	body	no	Optional deterministic version slot.

Operational notes

Use when uploading a new variant/version on an existing asset.
Follow with commit endpoint for the same asset id.

cURL

curl -X POST '$BASE/api/v1/dam/assets/123/files/presign' -H 'content-type: application/json' -d '{"filename":"hero_v2.jpg","mime":"image/jpeg"}'

polo-saas-api

session (oauth2-proxy headers)

POST/api/v1/dam/assets/:id/files

Commit new version on existing asset

Finalize version ingest for an existing asset and queue derivative jobs.

Param	In	Required	Description
`id`	path	yes	Target asset id.
`external_storage_key`	body	yes	Wasabi key from presign/upload.
`source_name`	body	yes	Source file name.
`mime`	body	yes	Source MIME.
`bytes`	body	yes	Uploaded byte size.

Operational notes

Use for manual versioning on the same asset.
Storage layout follows dam/{asset_code}/{asset_code}_v{n}_{token}.{ext}.

cURL

curl -X POST '$BASE/api/v1/dam/assets/123/files' -H 'content-type: application/json' -d '{"external_storage_key":"dam/AA000AA/AA000AA_v2_82ac19.jpg","source_name":"hero_v2.jpg","mime":"image/jpeg","bytes":285004}'

polo-saas-api

session (oauth2-proxy headers)

GET/api/v1/dam/ingest/profiles

List ingest profiles

Read configurable ingest/rendition profiles used by forms and defaults.

Param	In	Required	Description

Operational notes

Used by DAM control panel and admin tooling.
Profiles define web and thumbnail formats/sizes.

cURL

curl '$BASE/api/v1/dam/ingest/profiles'

polo-saas-api

admin session

GET/api/v1/dam/ingest/profiles/enabled

List enabled ingest profiles

Return only enabled profiles for upload forms and defaults.

Param	In	Required	Description

Operational notes

Use this endpoint for uploader profile dropdowns.
Avoid filtering manually on client side.

cURL

curl '$BASE/api/v1/dam/ingest/profiles/enabled'

polo-saas-api

admin session

POST/api/v1/dam/ingest/profiles

Create or upsert ingest profile by key

Create/update profile by stable profile_key.

Param	In	Required	Description
`profile_key`	body	yes	Stable profile key.
`label`	body	no	UI label.
`description`	body	no	Operational notes.
`enabled`	body	no	Enable profile for uploads.
`is_default`	body	no	Set as default profile.
`settings`	body	no	Preview/source settings payload.

Operational notes

Use when profile id is not known yet.
Prefer PATCH /:id for targeted edits on existing profile ids.

cURL

curl -X POST '$BASE/api/v1/dam/ingest/profiles' -H 'content-type: application/json' -d '{"profile_key":"default_web","label":"Default Web","enabled":true}'

polo-saas-api

admin session

PATCH/api/v1/dam/ingest/profiles/:id

Update ingest profile

Change profile settings (web/thumb sizes, format, quality, flags).

Param	In	Required	Description
`id`	path	yes	Profile id.
`settings.preview.*`	body	yes	Preview blocks: medium, thumb_large, thumb_medium, thumb_small (legacy aliases web/thumb kept).
`is_default`	body	no	Promote profile as default for new ingest.

Operational notes

Use future-only for immediate new ingest behavior.
Queue refresh separately when old assets must be regenerated.

cURL

curl -X PATCH '$BASE/api/v1/dam/ingest/profiles/1' -H 'content-type: application/json' -d '{"settings":{"preview":{"web":{"format":"webp","fit":"contain","width":1600,"height":1600,"quality":82}}}}'

polo-saas-api

admin session

POST/api/v1/dam/ingest/control-panel/preview/apply

Apply preview policy to existing assets queue

Apply new preview dimensions with future-only or queue-existing mode.

Param	In	Required	Description
`mode`	body	yes	future_only or queue_existing.
`limit`	body	no	Max assets to enqueue when queue_existing.
`payload`	body	no	Optional metadata persisted into refresh queue jobs.

Operational notes

future_only affects only new ingest.
queue_existing inserts refresh jobs with queue dedupe.

cURL

curl -X POST '$BASE/api/v1/dam/ingest/control-panel/preview/apply' -H 'content-type: application/json' -d '{"mode":"queue_existing","limit":5000,"payload":{"reason":"preset_update"}}'

polo-saas-api

admin session

GET/api/v1/dam/output-profiles

List print output profiles

Return tenant-scoped print output profile keys used for asset output files.

Param	In	Required	Description
`include_disabled`	query	no	Include disabled custom entries when true.

Operational notes

DAM owns these output profile keys and output files.
PIM should reference DAM asset/version/output identifiers, not redefine these profiles.

cURL

curl '$BASE/api/v1/dam/output-profiles?include_disabled=1'

polo-saas-api

session (oauth2-proxy headers)

POST/api/v1/dam/output-profiles

Create or update print output profile

Upsert tenant-scoped output profile entries (technology label, preferred extension, aliases).

Param	In	Required	Description
`key`	body	yes	Stable output profile key, for example cmyk or screen.
`label`	body	yes	Human readable label.
`code2`	body	yes	Two-char code family.
`extension`	body	no	Preferred extension for output naming.
`aliases[]`	body	no	Accepted aliases for matching.
`enabled`	body	no	Disable without deleting history.

Operational notes

Use this for DAM output formats/technologies, not for product taxonomy.
Product-specific enablement belongs in PIM by reference to DAM output profiles.

cURL

curl -X POST '$BASE/api/v1/dam/output-profiles' -H 'content-type: application/json' -d '{"key":"cmyk","label":"Quadricromia","code2":"CM","extension":"pdf","aliases":["four_color"],"enabled":true}'

polo-saas-api

admin session

GET/api/v1/dam/ingest/preview-mirror/jobs

List preview mirror queue jobs

Read mirror queue state for polo-preview sync.

Param	In	Required	Description
`status`	query	no	Filter by queue status.
`limit`	query	no	Page size.

Operational notes

Use for diagnostics when preview files are missing.
Queue states: queued, processing, retrying, done, dead_letter.

cURL

curl '$BASE/api/v1/dam/ingest/preview-mirror/jobs?status=retrying&limit=100'

polo-saas-api

admin session

POST/api/v1/dam/ingest/preview-mirror/dispatch

Dispatch preview mirror workers

Trigger queue dispatch for preview mirror processing.

Param	In	Required	Description
`limit`	body	no	Max jobs to dispatch this run.

Operational notes

Use when queue needs manual push in staging/testing.
Normal production flow should be automated by worker scheduler.

cURL

curl -X POST '$BASE/api/v1/dam/ingest/preview-mirror/dispatch' -H 'content-type: application/json' -d '{"limit":200}'

polo-saas-api

admin session

POST/api/v1/dam/ingest/preview/backfill-raster

Queue raster preview backfill

Backfill missing web/thumb previews for raster assets already stored.

Param	In	Required	Description
`limit`	body	no	Max assets scanned in this run.
`only_missing`	body	no	When true, queue only assets with missing previews.

Operational notes

Use after enabling preview generation on legacy assets.
Run in controlled batches to avoid queue spikes.

cURL

curl -X POST '$BASE/api/v1/dam/ingest/preview/backfill-raster' -H 'content-type: application/json' -d '{"limit":500,"only_missing":true}'

polo-saas-api

admin session