Start with the photo you already have. This guide walks through copying its image link from the Dashboard, changing the size and crop in the URL, and checking the image FileSpin returns.

You will then add responsive image markup and check format negotiation, so your page can request an appropriate image for the screen. The guide also shows where to update your application or feed to use the new URLs.

By the end: you will have working thumbnail, preview and email-image links from the same asset, plus a repeatable pattern for the rest of your catalogue.

For every parameter with more recipes (quality, effects, rotation, downloads), see the companion reference guide, On-Demand Image Transformations: A Practical Guide.

Image sizes, crop examples and format negotiation last verified on 9 September 2026 using the public demo assets below.

The short version: upload and process the asset once, then request delivery variants through URL parameters. On-demand outputs generated from Standard Image Conversion do not consume storage quota; stored originals and Custom Image Conversions are separate. Different dimensions use different URLs; supported browser formats can be negotiated at the same URL.

1. Get your first transformation link​

Every URL in this guide is the same shape, and the Dashboard will hand you one for your own asset. Start there rather than assembling a URL by hand.

1. Open a processed product image in the FileSpin Dashboard.
2. Choose Get link / Embed.
3. Ignore Temporary download link (original file). That link is signed, expires in 24 hours and returns the original file — it is not a transformation URL.
4. Under Permanent image links (resized), pick a size. Small, Medium and Large are 480×480, 1024×1024 and 2048×1536; Custom takes your own width and height.
5. Leave Format on Auto (best for each browser) for now. Section 4 explains what that setting does and when to override it.
6. Press Copy link.

You now have a working URL that looks like this:

https://<your-cdn-host>/api/v1/assets/<your-asset-id>/conversions?resize=480,480

That one link contains both things the rest of the guide needs:

Everything after the question mark is what the following sections change. The asset ID and host stay exactly as the Dashboard gave them to you.

The dialog also offers Copy <img> code if you would rather start from a complete tag.

Following along with the demo assets​

The examples below use FileSpin's public demo photos on cdn.filespin.io, so you can open every link as written before touching your own catalogue: a landscape photo, 2e1bc0f4159343779b82923e951a9256, for sizing, and a portrait, 3632004ce6214137b188e40e1c00af32, for the crop comparison. When you apply the pattern for real, substitute the host and asset ID from your own copied link.

Two conditions to check first​

The image must finish processing before its normal ODI output is available. The ODI overview explains the ON_DEMAND_IMAGE entry in addons_info. An image requested immediately after upload can temporarily return a low-resolution preview; allow processing to finish before assessing quality.

These examples use public delivery URLs. ODI URLs are always public. If a custom conversion is private, the dialog offers no permanent link and points you to the Public switch in the Formats tab instead; a private conversion needs an API key or JWT. Do not place an API key in browser code or a public image URL.

FileSpin normally renders ODI from its prepared Standard Image Conversion, so you do not need to export every requested delivery size yourself. Custom Image Conversions are a separate option: they are prepared and stored according to your account settings.

2. Request the sizes your channels need​

The Dashboard gave you one size. Your placements need several, and each is the same link with a different instruction after the question mark. Start with this working demo image:

https://cdn.filespin.io/api/v1/assets/2e1bc0f4159343779b82923e951a9256/conversions?resize=300,300

resize=300,300 fits the image inside a 300-by-300-pixel box while preserving its proportions. It does not necessarily return a square. The demo source is 4:3, and this request returns 300×225 pixels.

To try another output, keep the asset path and replace the text after ? with one of the parameter sets below. Use & between additional options.

Choose the transformation according to the layout:

These are example delivery requirements, not specifications for every app, email client or marketplace. Confirm the receiving system's requirements before choosing its output.

Open the padded card, app preview, email crop or partner image.

The four requests were checked on the public demo asset: the outputs are 300×300, 600×450, 960×480 and 720×720 pixels respectively. All four requests use the same asset ID. If the storefront needs a larger card later, update the URL rule that constructs its image links; the existing asset can supply the new size.

For the complete syntax, see Resize, Crop and Format.

3. Make the storefront responsive​

Keep placement sizes in a shared image component or feed configuration. When a placement changes, update that rule and deploy it through your normal application or CMS workflow. The stored asset can remain the same.

For a website, the browser also needs to know which image sizes are available. ODI supplies the images; HTML supplies the selection hints.

This example assumes a product card displayed at 300 CSS pixels on larger screens and nearly the viewport width on screens up to 600 pixels wide. The 300, 600 and 720-pixel crops provide candidates for different display densities. Use a source large enough for the largest candidate.

<img
  src="https://cdn.filespin.io/api/v1/assets/2e1bc0f4159343779b82923e951a9256/conversions?crop=300,300,center"
  srcset="
    https://cdn.filespin.io/api/v1/assets/2e1bc0f4159343779b82923e951a9256/conversions?crop=300,300,center 300w,
    https://cdn.filespin.io/api/v1/assets/2e1bc0f4159343779b82923e951a9256/conversions?crop=600,600,center 600w,
    https://cdn.filespin.io/api/v1/assets/2e1bc0f4159343779b82923e951a9256/conversions?crop=720,720,center 720w
  "
  sizes="(max-width: 600px) calc(100vw - 32px), 300px"
  width="300"
  height="300"
  style="display: block; width: 100%; max-width: 100%; height: auto;"
  alt="Demo photograph of a woman wearing a white top"
/>

This example crops because the demo is a lifestyle photo. For product cut-outs where the whole item must stay visible, use padding instead: resize=300,300,fill:white, and the same for the 600 and 720 candidates.

Match sizes to your actual layout and replace the example alt text with a useful description of the product. The w descriptors must match the returned image widths. Check those widths if the source is small or delivery constraints apply.

The browser uses srcset and sizes to choose a candidate. The asset endpoint does not discover your CSS layout and choose a new width on its own. See the HTML image element reference for how these attributes work.

4. Allow browser format negotiation​

The responsive example deliberately omits format. For supported browser requests, FileSpin can choose AVIF or WebP using the Accept request header. AVIF delivery must be enabled in the serving environment. For ordinary JPEG delivery, the fallback is JPEG; PNG sources retain a transparency-capable fallback.

For the 300×300 demo URL above, live requests returned image/avif when AVIF and WebP were offered, image/webp when WebP was offered, and image/jpeg when JPEG was requested. All three returned 300×300 pixels. The output format changed while the URL and pixel dimensions stayed the same.

This is the part that works at the same URL. You do not need separate AVIF, WebP and JPEG URLs in your markup just to negotiate formats. You still need the size-selection markup from the previous section.

To check delivery, open your browser's Network panel, reload the image and inspect:

1. The image request's Accept header.
2. The response's Content-Type, such as image/avif, image/webp or image/jpeg.
3. The rendered dimensions and transferred bytes.

The extensionless URL alone does not tell you the returned format. When a downstream system needs a fixed format, specify it explicitly:

https://cdn.filespin.io/api/v1/assets/2e1bc0f4159343779b82923e951a9256/conversions?crop=960,480,center&format=jpg

Use an agreed format for email and partner feeds, then test it in the receiving systems. FileSpin's Campaign Link Builder also specifies JPEG for its default email-hero placement. That choice avoids depending on browser-style format negotiation in an email workflow.

5. Choose crops deliberately​

A portrait does not automatically make a good wide banner. Use the second public demo photo to compare two 600×300 crops:

https://cdn.filespin.io/api/v1/assets/3632004ce6214137b188e40e1c00af32/conversions?crop=600,300,center&format=jpg
https://cdn.filespin.io/api/v1/assets/3632004ce6214137b188e40e1c00af32/conversions?crop=600,300,face&format=jpg

Centre crop	Face-aware crop

Open the centre crop or face-aware crop to inspect the full output.

Both images are actual FileSpin outputs at 600×300 pixels. In this example, the centre crop cuts through the upper part of the face. The explicit face option shifts the crop upward to keep the face in frame. Only the alignment parameter changes.

Review both outputs. Smart cropping is useful when the person is away from the centre, but it cannot guarantee that every face, garment detail or brand mark stays visible. For product cutouts where the whole object matters, use proportional resizing with padding. For art-directed photography, choose an explicit alignment or crop region and inspect the result.

The Campaign Link Builder applies this same idea to selected channel placements: it constructs image URLs with placement dimensions and tracking parameters. Keep its output tied to the receiving channel's needs, and inspect tall crops rather than assuming a preset guarantees the final resolution.

6. Check delivery before expanding​

The published ODI overview describes a standard delivery envelope of 2048 pixels wide by 1536 pixels high, with 72 PPI metadata. Keep this walkthrough inside that envelope. The Dashboard's own Custom size clamps to those bounds before it builds a link, which is a useful confirmation of where the ceiling sits.

A URL accepting your dimensions is not proof of the resulting resolution. The source matters as much as the ceiling. Requesting resize=3000,3000 from the landscape demo asset returns HTTP 200 and a perfectly good image — at 1024×768, because resize fits within bounds and does not upscale, and that is the largest output this asset has to give. Nothing in the response announces the difference. Check the pixel dimensions you actually received, especially for your largest placement.

Pixel dimensions determine how much image detail you have for a screen. Changing the quality parameter does not turn a standard ODI output into an archival master or a print export. Use the original or an appropriately configured conversion when you need that output.

For a catalogue rollout:

On-demand outputs generated from Standard Image Conversion do not consume storage quota. Stored originals and Custom Image Conversions are separate, and processing and delivery remain subject to your account's terms — none of this makes the pipeline free. Assess your account's usage and commercial terms separately. A useful pilot measures image bytes, request performance and the work required to change a placement, rather than assuming a universal savings percentage.

Best practices​

Keep your size and crop rules in one shared place. Use a bounded set of sizes so every small layout change does not create another delivery variant. Preserve the whole product where its details matter, and use explicit smart cropping for suitable lifestyle photos.

Next steps​

Choose one product category and connect its card, detail view and email image to the same FileSpin assets. Check the outputs, then change one placement size through the shared URL rule. That is a small, repeatable test of ODI's value in your own catalogue.

• ODI overview and limitations
• Resize and padding
• Crop alignment
• On-Demand Image Transformations: A Practical Guide: every parameter, with recipes
• Build repeatable workflows

If your team uploads thousands of images a week, processing each one through an AI addon by hand gets old fast. You either remember to run Face Recognition on every batch, or you accept that auto-tagging only happens for assets someone thought to process. Neither scales.

FileSpin's Automated Media Pipeline solves this. You configure each addon once in the Dashboard — which events to listen to, which content types qualify, which custom metadata patterns to match — and the platform runs the addon for you whenever an asset event fires. Upload a portrait, Face Recognition runs. Tag a product photo as an original, Remove Background fires and saves a transparent PNG. Edit metadata on a stock image, Image Analysis re-evaluates only if the criteria still match.

This guide walks through the Dashboard setup for all three addons, with examples covering the most common automation patterns. For the conceptual reference, see Automated Media Pipeline.

How addon automation works​

Three filters decide whether an addon runs on a given asset event:

Asset event fires
       │
       ▼
┌─────────────────┐
│ Event hook      │  → Is the addon listening for this event type?
└─────────────────┘     (file-saved, file-data-updated)
       │
       ▼
┌─────────────────┐
│ Content type    │  → Does the asset's MIME type match?
└─────────────────┘     (image/*, image/jpeg, */*, etc.)
       │
       ▼
┌─────────────────┐
│ Schema criteria │  → Does the asset's schema and custom data match?
└─────────────────┘     (only on file-data-updated)
       │
       ▼
   Run addon

Each addon is configured independently. You can have Face Recognition running on every upload, Image Analysis scoped to a "Stock Library" schema, and Remove Background firing only when a product photo is flagged as an original — all from the same upload event.

The platform also handles dedup automatically. When an addon completes, it writes a system marker to the asset's metadata (any field beginning with _filespin_). On any subsequent event, if the marker is present, the addon is skipped — no double-billing, no duplicate processing.

Setting it up in the Dashboard​

Go to Settings → Addons and click the gear icon next to the addon you want to automate.

The configuration modal has three sections, in order:

1. Event hooks — pick which events the addon listens to.
2. Schema criteria — restrict the file-data-updated hook to assets matching a schema or specific field values.
3. Disposition — addon-specific output options.

Step 1 — Pick your events​

For each event type (file-saved, file-data-updated), toggle it on if the addon should listen, and choose the content types that qualify. Most image addons want image/*.

A good default for most workflows:

Step 2 — Add schema criteria (optional)​

Schema criteria only apply to file-data-updated — fresh uploads have no custom metadata yet, so criteria can't be evaluated on file-saved.

Two filters, both optional, both applied:

• Schema — pick a schema to restrict the addon to assets following it. Useful when you want different addons for different content types (e.g. Face Recognition on "Event Photo" assets, Remove Background on "Product Photo" assets).
• Fields — add one or more key → value pairs. The asset's metadata must contain the key, types must match, and string matching is by substring (so "GM" matches "GM-2024" and "BGM"). Booleans match exactly.

Leave both empty if you want the addon to fire on every asset whose content type matches.

Step 3 — Choose the disposition​

The disposition section is where the addons differ. Each addon's options are documented inline in the Dashboard, but here's what each one means.

Face Recognition​

Two toggles:

• Tag asset with face count and IDs — when on, the asset's metadata is enriched with a face count and the IDs of detected faces, which makes them searchable in the Dashboard. When off, the face index still gets built (so face search keeps working), but the asset's metadata stays clean.
• Process derived assets (default off) — when off, FR skips system-generated derivative assets like background-removed PNGs. Leave this off unless you specifically want FR to also index faces in cut-outs (it would create duplicate entries — one from the original photo, one from the cut-out — and pollute face search results).

Image Analysis​

A single toggle: Process derived assets (default off). When off, IA skips system-generated derivative assets like background-removed PNGs. Leave this off unless you specifically want auto-tags on cut-outs — they tend to produce noisy labels because transparent-background images confuse general-purpose vision models.

Remove Background​

Two output modes:

• Add as conversion — saves the cut-out as a named conversion on the source asset (default name: bg_removed). The original stays canonical; the cut-out is a sibling visible in the Dashboard and in branded share pages with signed URLs. Best when the cut-out is a deliverable, not its own asset.
• Add as new asset — creates a brand-new PNG asset, linked back to the source. Optionally inherit the source's custom metadata and schema assignment. Best when the cut-out needs its own ID, share permissions, or independent metadata.

Switching modes clears the now-irrelevant fields automatically — pick Add as conversion and the conversion name input appears; pick Add as new asset and the inherit-metadata checkbox appears instead.

Common automation patterns​

Index every face in every uploaded image​

Goal: build a searchable face index from every photo on upload, regardless of how it's tagged.

Auto-tag only assets in the Stock Library schema​

Goal: run Image Analysis only when an asset is assigned to your Stock Library schema, not for press releases or working files.

The file-saved hook fires on every image upload, so Image Analysis still runs immediately when an asset is created. The file-data-updated hook handles the case where someone re-classifies an asset into the Stock Library schema later.

Auto-cut backgrounds for original product photos only​

Goal: when a product photo is marked as an original (not a re-upload of an existing image), automatically generate a transparent-background version.

The cut-out lands on the same asset as a bg_removed conversion, accessible in the Dashboard and in branded share pages.

Auto-cut backgrounds and create a separate asset​

Goal: same as above but the cut-out should be its own asset, not a conversion.

The new PNG inherits the source's metadata and schema, and links back to the original. Remove Background won't loop on the new asset — the platform detects derived assets and excludes them from matching.

Best practices​

Start with file-saved and no criteria. Schema criteria are useful, but they're easy to over-tune. Begin with a simple "run on every image upload" config, observe what the addon produces, then narrow down.

Use the schema filter before fields. Schema-level filtering is exact and fast; field matching is substring-based and easier to get wrong. If your goal is "only run on Marketing assets", point the schema filter at the Marketing schema rather than building a fields filter.

Marker fields are platform-managed. Anything starting with _filespin_ is owned by FileSpin and shown read-only in the Dashboard. Don't rely on these for your own metadata — define your own fields in your schema instead.

Next steps​

• Automated Media Pipeline reference — what each setting does and per-addon disposition options
• Face Recognition guide — face indexing, search, and pagination
• Background Removal — manual triggering, asset-based and upload-based modes
• Asset Schemas guide — designing the schemas that drive your criteria

FileSpin offers three automation paths: AI agents for ad-hoc, complex workflows through natural language; workflow engines for repeatable, visual pipelines operations teams build without engineering; and REST APIs for custom, high-throughput integrations. This guide covers the second path — workflow engines.

FileSpin provides native modules for Make, Zapier and n8n that wrap the FileSpin REST API into drag-and-drop building blocks — real-time triggers, actions, and searches (24+ modules). Your operations team can build end-to-end media automation pipelines that react to uploads, processing completions, metadata changes, and errors — then push results to downstream systems. No code required.

How it works​

The architecture has three layers:

1. FileSpin fires a trigger event — when an asset is uploaded or processing completes, FileSpin's native trigger modules deliver the event to your workflow engine in real time. The trigger modules handle webhook registration automatically — no manual setup needed.

2. The workflow engine executes a pipeline — using FileSpin's native action modules to perform operations (search, transform, remove background, tag, share, watermark) and any other connected service modules (commerce platforms, Slack, Salesforce, etc.) for downstream actions.

3. Results flow to downstream systems — transformed assets pushed to storefronts, metadata synced to PIMs, share pages delivered to stakeholders, notifications sent to teams.

This is event-driven automation. Nothing polls. Nothing waits. The moment an asset event occurs in FileSpin, your pipeline runs.

Triggers: what starts your pipeline​

Every workflow starts with a trigger. FileSpin's native modules include six webhook-based trigger types that fire instantly when asset events occur — no polling delays.

Which trigger to use​

For most automation pipelines, Asset Processing Complete is the primary trigger — it fires when the asset is fully ready with all conversions and transcodes available. Use Addon Processing Complete when your pipeline depends on AI results (auto-tags, face recognition, background removal). Use New Asset Uploaded when you need to react to the upload itself before processing finishes — for immediate notifications, metadata validation, or routing logic. Asset Processing Failed enables error-handling workflows that alert your team or retry operations.

Connecting your FileSpin account​

All three platforms authenticate with FileSpin using OAuth 2.0 Authorization Code flow. When you add a FileSpin connection, the platform opens a browser window for you to log in to FileSpin and grant permissions. The platform manages token refresh automatically — no API keys or manual token handling required.

The trigger modules handle webhook registration behind the scenes — when you activate a scenario, the module registers a webhook with FileSpin; when you deactivate, it cleans up. No manual webhook management required.

FileSpin's native modules​

FileSpin provides 24+ native modules for Make, Zapier, and n8n — all available on all three platforms with identical functionality. Instead of configuring HTTP requests manually, you drag and drop FileSpin actions into your pipeline and configure them with business-friendly fields.

Actions — asset management​

Actions — image processing​

Actions — AI and addons​

Actions — sharing and collections​

Searches​

These modules cover the full asset lifecycle: ingest (upload), process (resize, remove background, auto-tag), organise (metadata, collections), distribute (share pages, download links), and search (full-text, face search). Combined with FileSpin's six triggers, you can build end-to-end automation that reacts to asset events and composes with thousands of other apps on each platform.

Build your pipeline​

Common pipeline patterns​

E-commerce: New product → marketplace-ready images

Trigger: Asset Processing Complete
  → Filter: check content_type is image
  → FileSpin: Generate Marketplace Image (Amazon, 1600×1600)
  → FileSpin: Generate Marketplace Image (website-hero, 1920×600)
  → FileSpin: Generate Marketplace Image (Instagram square, 1080×1080)
  → Commerce Platform: Update Product Image
  → Slack: Notify #product-images channel

Events: Speaker photos → press distribution

Trigger: Asset Processing Complete
  → Filter: check metadata for event tag
  → FileSpin: Update Metadata (speaker, session, event name)
  → FileSpin: Generate Social Media Kit (LinkedIn + Instagram)
  → FileSpin: Create Share Page (branded press page, expiry 1 week)
  → Email: Send share URL to press list
  → Slack: Post to #event-comms

Content publishing: Asset ready → push to CMS

Trigger: Asset Processing Complete
  → Filter: check metadata for status = "approved"
  → FileSpin: Generate Marketplace Image (desktop 1920×600, tablet 1024×400, mobile 640×300)
  → CMS: Create/Update Asset Entry
  → CMS: Publish Entry

Brand compliance: New upload → metadata validation

Trigger: New Asset Uploaded
  → FileSpin: Get Auto Tags (detect content type, categories)
  → Router:
    → IF metadata complete: FileSpin: Update Metadata (status = "approved")
    → IF metadata missing: Email: Notify uploader to complete fields
    → IF wrong format: Slack: Alert #brand-compliance

Sponsor deliverables: Post-event asset distribution

Trigger: Addon Processing Complete (face indexing)
  → FileSpin: Find Asset (by sponsor tag + event)
  → FileSpin: Create Share Page (branded sponsor page, password protected, approval enabled)
  → Email: Send share URL + password to sponsor contact
  → Google Sheets: Log delivery in sponsor tracking sheet

Recipe walkthrough: E-commerce product pipeline in Make​

Here's a step-by-step walkthrough of building the e-commerce product pipeline in Make:

1. Asset Processing Complete trigger Add a FileSpin → Asset Processing Complete trigger module. This automatically registers a webhook with FileSpin — when an asset finishes processing, it fires.

2. Filter: images only Add a filter after the trigger: content_type contains image/. This skips video and document assets.

3. FileSpin: Generate Marketplace Image (Amazon) Add a FileSpin → Generate Marketplace Image module. Map the asset ID from the trigger payload. Select the "Amazon" preset, or set width and height to 1600, crop mode to center, format to webp, quality to 90.

4. FileSpin: Generate Marketplace Image (website hero) Clone the previous module. Select the "website-hero" preset or change dimensions to 1920x600.

5. FileSpin: Generate Marketplace Image (Instagram) Clone again. Select the "Instagram square" preset or change dimensions to 1080x1080.

6. Commerce platform: Update Product Add your commerce platform module. Map the product by SKU from the trigger's custom metadata fields. Attach the generated image URLs as product images.

7. Slack: Send notification Add a Slack module. Post to #product-images with the product name, SKU, and a summary of generated sizes.

The entire pipeline runs automatically every time a product image is processed in FileSpin.

Recipe walkthrough: Event photo distribution in n8n​

1. Asset Processing Complete node Add a FileSpin trigger node. Select "Asset Processing Complete" as the event type. This registers a webhook with FileSpin automatically.

2. IF node: event assets only Route based on whether event_name exists in the asset's custom metadata.

3. FileSpin: Update Metadata Use the FileSpin Update Metadata node. Map speaker name, session, and event from the asset's custom metadata.

4. FileSpin: Create Share Page Use the Create Share Page node. Set the title to the event name + speaker, enable approval workflow, set expiry to one week, and apply branding.

5. Send Email node Send the share URL to the press distribution list pulled from a Google Sheet or Airtable base.

6. Slack node Post to #event-comms with the share URL and a count of assets included.

Pre-built recipes and building blocks​

FileSpin publishes production-ready workflow templates — pre-built recipes — that you can import directly into Make, Zapier, or n8n and customise to your stack.

These are not black-box connectors. Every step is visible, modifiable, and composable. Deploy as-is for standard workflows or adapt them to match your exact process.

New recipes are published regularly. Check the FileSpin documentation for the latest library.

Why recipes, not rigid connectors:

• You see every step. No hidden logic. When something breaks, you know exactly where and why.
• Your ops team builds. Recipes run on visual platforms your operations team already knows — no engineering tickets.
• Every stack is unique. Combine, extend, and chain recipes to match how your team actually works.

Webhook reliability​

FileSpin's trigger modules are backed by enterprise-grade webhook delivery:

• At-least-once delivery — events are retried with exponential backoff if delivery fails, up to 8 retries over 8 hours.
• HMAC-SHA256 signing — every payload is cryptographically signed. The trigger modules verify signatures automatically; if you build custom webhook handlers, verify the X-FileSpin-Signature header to ensure the request comes from FileSpin.
• Idempotency — use the delivery_id field as a deduplication key. Your pipeline may receive the same event more than once during retries.
• Automatic registration — trigger modules handle webhook registration and deregistration as you activate and deactivate scenarios. No manual webhook management.

Best practices​

1. Trigger on Asset Processing Complete, not New Asset Uploaded for distribution workflows. The New Asset Uploaded trigger fires before processing is complete — conversions, transcodes, and addon results aren't available yet. Use Asset Processing Complete for pipelines that need the fully ready asset.

2. Use filters early in the pipeline. Not every asset event needs the full pipeline. Filter by content type, metadata values, or asset status immediately after the trigger to avoid unnecessary processing.

3. Handle idempotency. Network retries can deliver the same event twice. Use delivery_id to detect duplicates — check if you've already processed this delivery before running the pipeline.

4. Use named presets in Generate Marketplace Image. Presets let your ops team think in channels ("Amazon", "Instagram Story", "website-hero") instead of pixels. Define your team's presets in the FileSpin dashboard and they'll appear in the module dropdowns automatically.

5. Use Addon Processing Complete for AI-dependent workflows. If your pipeline depends on face recognition, background removal, or auto-tagging results, use the Addon Processing Complete trigger instead of Asset Processing Complete — it fires specifically when the addon finishes, so your pipeline only runs when those results are available.

6. Keep pipelines modular. Build small, focused scenarios rather than one large pipeline. A scenario that tags + shares is easier to debug than one that tags + shares + pushes to three CMSs + notifies four channels.

7. Use Update Metadata to close the loop. After your pipeline runs, write status back to FileSpin — mark assets as "distributed", "published", or "synced". This makes search workflows and audit pipelines possible downstream.

Comparison with other DAM platforms​

Next steps​

• Using FileSpin within an AI Agent — For complex, ad-hoc workflows through natural language
• Real-time Notifications with Webhooks — Deep dive into webhook setup, HMAC verification, and handler code
• Upload, Process, Deliver: The Complete Asset Lifecycle — Understand the events in context
• Sharing Assets with External Stakeholders — Branded share pages for distribution workflows

FileSpin offers three automation paths: AI agents for ad-hoc, complex workflows through natural language; workflow engines for repeatable, visual pipelines operations teams build without engineering; and REST APIs for custom, high-throughput integrations. This guide covers the first path -- AI agents.

FileSpin is an AI-native digital asset management platform used by eCommerce retailers, event producers, attractions operators, and media companies to manage, transform, and deliver assets autonomously. One of the most powerful ways to interact with FileSpin is through AI agents -- Claude, ChatGPT, Mistral or any MCP-compatible client -- that connect to the platform via the Model Context Protocol and execute complex media workflows through natural language.

Instead of learning API endpoints and building integration code, your team describes what they need: "Tag all new arrivals by SKU, remove backgrounds, and send a review link to the buying team." The agent discovers FileSpin's capabilities, chains the right operations together, and executes the entire workflow end-to-end.

This guide covers the architecture, setup, available capabilities, and real-world workflow patterns so your engineering team can evaluate and integrate FileSpin's MCP server.

What is the Model Context Protocol (MCP)?​

MCP is an open standard that lets AI agents discover and use external tools. Instead of hard-coding API calls or building custom plugins, an MCP server advertises its capabilities -- tools and prompt templates -- and any compatible AI agent can discover and invoke them at runtime.

FileSpin's MCP server exposes the full FileSpin platform as a focused set of tools and prompt templates across 11 workflow categories. The agent connects to FileSpin MCP, authenticates via OAuth2, and has access to every operation your FileSpin account role permits.

Key concepts​

How it works​

When an AI agent connects to the FileSpin MCP server, the interaction follows three phases: the agent discovers available capabilities, executes a chain of tool calls to fulfill the user's request, and returns the result.

The agent handles all orchestration -- deciding which tools to call, in what order, with what parameters -- based on the user's natural language request. The MCP server translates each tool call into the corresponding FileSpin REST API request.

Step 1: Configure the FileSpin MCP server​

FileSpin The MCP URL: https://mcp.filespin.io/mcp

Claude Desktop​

Add FileSpin to your Claude Desktop via Settings -> Connectors.

ChatGPT and other MCP clients​

Any MCP-compatible client can connect to the FileSpin MCP server. Add the MCP server using standard connector option.

Step 2: Authentication and permissions​

The FileSpin MCP server uses standard OAuth2 authentication. When the agent connects, it authenticates through the OAuth2 flow (i.e. a broser window opes and user is asked to authenticate FileSpin MCP by logginh into FileSpin). The agent receives a token scoped to the authenticating user's FileSpin account role after successful login.

What the agent can do is determined entirely by the FileSpin account role of the authenticated user. If the user has read-only access, the agent can only read. If the user has full admin access, the agent can upload, tag, share, and manage assets.

This means:

• No separate API key scoping -- the agent inherits the user's existing permissions.
• Audit trails -- every action the agent takes is logged under the authenticated user's account.
• Role-based control -- restrict what agents can do by assigning appropriate FileSpin roles to the users who connect agents.

Let the AI get you started​

The quickest way to get started is to let the AI Agent such as Claude or ChatGPT guide you in using FileSpin MCP. When FileSpin MCP is added to the AI Agent, it provides the AI Agent with comprehensive information to guide you in using it. Start with the prompt:

Help me get started with FileSpin MCP, walk me through the prompts and workflows I can do - starting with how to login, find assets and have them reviewed and finalised

Available tools​

The FileSpin MCP server exposes a focused set of tools that agents can call directly. These are atomic operations -- the building blocks that agents compose into workflows. They are an intelligence layer on top of FileSpin REST APIs that securely mediate the AI Agent's calls to the FileSpin API.

Prompt templates -- pre-built workflow recipes​

Prompt templates are the most powerful feature of the FileSpin MCP server. They are multi-step workflow recipes that guide the agent through complex operations. The agent discovers them automatically, and when invoked, receives a structured message that tells it exactly which tools to call and in what order.

The prompt templates are organised across 11 categories:

Industry-specific workflows​

Platform workflows​

How prompts work​

When a user says "Process all product images from the summer shoot", the agent matches this to the prompt template and receives:

Process product images matching "summer shoot" uploaded recently:

1. Find images matching "summer shoot".
2. Discover the available metadata schema, then bulk-tag the matching assets with
   campaign = "Summer Campaign", category = "product", status = "ready".
3. Generate Instagram feed and Facebook post versions using branded image transformation.
4. Create a branded review page with approvals enabled for the buying team.

Give me the share URL and a summary of assets processed.

The agent then executes each step, calling the appropriate tools in sequence, handling responses, and reporting back to the user.

Workflow patterns​

When agents compose multi-step workflows -- whether guided by prompts or working from free-form instructions -- they follow a few canonical sequences:

Discovery first​

Before operating on assets, the agent checks what addons are enabled, discovers the available metadata schemas, and searches for assets matching the user's request.

Single-asset inspection and delivery​

The agent fetches the asset's details, then returns a viewable CDN URL, a signed download URL, or a resized/cropped variant as needed.

Metadata workflows​

The agent discovers the relevant schema, then updates fields on a single asset or bulk-tags many assets at once.

External sharing​

The agent searches for the target assets (or picks up a collection), creates a branded share page, and can later pull analytics or approval status for that share.

Video workflows​

The agent inspects the asset's existing conversions, transcodes or clips as required, and returns a streaming URL.

Real-world example: E-commerce product pipeline​

User prompt: "Tag all new arrivals by SKU, remove backgrounds, and send a review link to the buying team."

Here's what the agent does:

1. Discover context. Confirms the Background Removal addon is enabled and retrieves the relevant metadata schema (fields: sku, category, status, campaign).
2. Find assets. Searches for recent "new arrivals" and returns 24 product images uploaded in the last 7 days.
3. Tag with metadata. Bulk-tags all 24 assets with category = "new-arrival", status = "pending-review", campaign = "Spring 2026".
4. Create review share. Creates a branded share page titled "Spring 2026 New Arrivals -- Review" with approvals and feedback enabled, expiring in seven days.

Agent response to user: "Done. 24 new arrival images tagged with Spring 2026 campaign metadata. Review page with approval workflow that includes Social media versions: https://app.filespin.io/shared/sh_abc123 -- the buying team can approve or reject each image directly."

Real-world example: Event photo distribution​

User prompt: "Find all photos of the keynote speaker, tag by session, and build a branded share page for the press team."

Here's what the agent does:

1. Face search. Uses the speaker's headshot to find all photos of this person across the event -- returns 87 matches with high matching strictness.
2. Tag by session. Retrieves the event schema and bulk-tags the 87 matching assets with speaker = "Jane Smith", session = "Opening Keynote", event = "TechConf 2026".
3. Branded press share. Creates a share page titled "TechConf 2026 -- Jane Smith Keynote Photos" with company branding (logo from watermark, primary colour #1a73e8), feedback enabled, expiring in one week.

Agent response: "Found 87 photos of Jane Smith across all event sessions via face recognition. Tagged with speaker, session, and event metadata. Press share page with Social media crops: https://dashboard.filespin.io/shared/sh_press456"

Addon availability and runtime checks​

Some capabilities depend on addons being enabled on your FileSpin account. The agent always verifies addon availability before attempting addon-dependent operations by querying the account's enabled addons through the MCP server.

If an addon isn't enabled, the agent will report this to the user rather than failing silently.

Best practices​

1. Create a dedicated agent user. Set up a FileSpin user account specifically for AI agent access. Assign the appropriate role for the agent's intended workflows. This gives you a clean audit trail and precise permission control.

2. Use prompt templates for common workflows. Prompts encode best practices -- correct tool ordering, required checks, and sensible defaults. They're faster and more reliable than free-form instructions for repeatable operations.

3. Check addon availability first. Have the agent call ask which addons are available before attempting face recognition, auto-tagging, or background removal to verify the addon is enabled.

4. Use collections for internal grouping, shares for external distribution. Collections are for your team's organization. Shares create branded, trackable pages for external stakeholders -- with download controls, approval workflows, and analytics.

5. Let the agent handle orchestration. Don't try to script every tool call. Describe the outcome you want and let the agent decide which tools to chain and in what order. This is what MCP is designed for.

Cloud-only operation assumes reliable internet. For most teams -- eCommerce, agencies, publishing -- that assumption largely holds. But event venues with unreliable Wi-Fi, attractions that process and deliver media, remote sites with no connectivity, and operations with data sovereignty requirements -- cloud-only breaks down.

Teleport is FileSpin's hybrid deployment model. A single binary that runs the core media processing pipeline on your local hardware -- ingest, transform, watermark, transcode, search, deliver -- with zero internet dependency. When connected, cloud-powered features like face recognition and background removal activate in real time. Once assets sync to FileSpin Cloud, the full intelligence layer takes over: AI agents, workflow engines, extended APIs.

This guide covers the architecture, installation, local APIs, hot-folder workflows, and cloud sync -- everything your engineering team needs to deploy and integrate Teleport.

Architecture: Three capability tiers​

Teleport's capabilities scale with connectivity. Nothing fails when the network drops -- features degrade gracefully across three tiers.

The Always Local tier is Teleport's foundation. It runs entirely on your hardware -- no cloud round-trip, no upload queue, no network dependency. The other two tiers add intelligence as connectivity permits, but local operations never wait for them.

What Teleport exposes locally​

Teleport monitors the designed hot folder for assets. It also runs a REST API server on your hardware that mirrors a subset of the FileSpin Cloud API -- the endpoints built for local operations. Your capture systems, POS, and guest apps integrate via these local endpoints at local speed.

Hot-folder ingest​

Drop files into a watched directory and Teleport processes them automatically -- no API calls required.

The file watcher detects new files, validates them, assigns an asset ID, queues them for upload, and moves them through the lifecycle. Configurable stability wait handles files still being written -- critical for network drives and large transfers.

REST API endpoints​

Authentication uses the same X-FileSpin-Api-Key header as the Cloud API. Teleport validates locally against your configured API key.

Web dashboard​

Teleport includes a local web UI.

Dashboard Home

Install Teleport​

Teleport is a single binary. No dependencies, no runtime, no container. Download and install as a service on Windows, Mac or Linux.

Get in touch to start a Free Trial

Hardware benchmark​

Teleport includes a built-in benchmark to evaluate your hardware before deployment. Use the Performance Tests option in Teleport Web Dashboard or execute it via commandline for automated tests.

# Interactive web UI
teleport --benchmark

# CLI output (headless, for automation)
teleport --benchmark --headless --output text

The benchmark measures API throughput, image processing speed, file I/O performance, and video delivery -- and produces a performance score with specific latency percentiles.

Configure Settings​

Hot folder and cache purge settings​

Use the Settings page to update the hot folder settings.

Retention settings​

Asset Retention Policies. Configure which assets should be retained and never purged. Add asset IDs or create metadata-based rules.

Local-only Assets Settings​

Local-only assets for total privacy control. Configure rules for assets that should be kept locally and not uploaded to FileSpin Cloud.

Multi-Site Visibility via Cloud Dashboard​

Cloud dashboard monitors all Teleport instances. Status, performance, and telemetry across distributed deployments.

Fetch from Cloud​

Fetch assets selectively from Cloud for local-first delivery. Use this to bring centrally managed assets for local delivery. Deliver event media on-site without worrying about internet connectivity.

Recipe walkthrough​

Event photography pipeline​

A conference photography team captures thousands of images over a multi-day event. Venue Wi-Fi is unreliable. Sponsors expect same-day delivery. The social team needs platform-ready variants during sessions.

1. Deploy Teleport at the venue Install Teleport on a venue server or workstation. Configure the hot folder path and FileSpin Cloud connection. Takes under 10 minutes.

2. Photographers dump camera cards to the hot folder Photographers ingest directly -- drag camera card contents to the hot folder, or configure their tethering software to write to it. Teleport detects files, assigns asset IDs, and begins processing.

3. Generate social variants locally Your integration calls the conversions endpoint to generate platform-ready sizes:

# Instagram square
curl "http://localhost:8080/api/v1/assets/{id}/conversions?resize=1080,1080&format=jpg" \
  --output ig.jpg

# LinkedIn landscape
curl "http://localhost:8080/api/v1/assets/{id}/conversions?resize=1200,627&format=jpg" \
  --output linkedin.jpg

All processed locally -- no upload wait, no cloud latency.

4. Apply event watermarks Use the conversions endpoint with watermark parameters to brand assets before distribution.

5. When venue Wi-Fi connects -- cloud pass-through activates Face recognition identifies speakers and VIPs across thousands of photos in real time. Branded share pages become available for sponsor distribution. If connectivity drops, local processing continues.

6. Assets sync to FileSpin Cloud Once synced, the full automation stack activates: AI auto-tagging classifies by session, speaker, and sponsor. Make/Zapier pipelines trigger downstream distribution -- press kits, social scheduling, sponsor deliverables.

Attractions guest imaging​

A theme park processes millions of guest photos daily. The business runs on preview-to-purchase -- if the watermarked preview is slow, the sale is lost.

1. Ride capture system uploads via REST API The capture system sends photos to Teleport's upload endpoint immediately after capture:

curl -X POST "http://localhost:8080/api/v1/assets/new/content/original/upload" \
  -F "file=@ride-photo-001.jpg" \
  -F "data={\"ride\":\"coaster-1\"}"

2. Generate watermarked preview locally The guest app requests a watermarked preview via the conversions endpoint -- sub-10ms response, no cloud round-trip:

curl "http://localhost:8080/api/v1/assets/{id}/conversions?resize=800,600&watermark={params}" \
  --output preview.jpg

Guest sees the preview the moment they step off the ride.

3. Face recognition links captures across the park (when connected) At connected venues, Teleport's cloud pass-through enables face recognition in real time -- a single face search discovers photos from rides, meet-and-greets, roaming photographers, and green screen stations. Unified guest galleries drive cross-venue photo discovery and incremental sales.

4. Purchase triggers high-quality download On purchase, the guest app requests the unwatermarked original via get_link:

curl "http://localhost:8080/api/v1/assets/{id}/get_link"

5. Selective sync to cloud Not every guest photo needs cloud backup. Configure sync rules to upload purchased photos, flagged assets, or a configurable percentage -- typically 15–20% of total captures. The rest stays local with configurable retention.

Awards festival judging​

A creative awards festival runs on-site judging across multiple jury rooms. Entries include 30-second films, print campaigns, digital experiences, and case study videos. Jury panels need instant video playback and high-res image viewing -- but venue Wi-Fi collapses under load. The old way: USB drives shuttled between rooms, inconsistent playback quality, and no way to search or filter entries during deliberation.

1. Deploy Teleport at the venue Install Teleport on a workstation in each jury room -- or a single server serving multiple rooms over the local network. Configure the FileSpin Cloud connection and run the benchmark to confirm playback performance meets requirements.

2. Fetch shortlisted entries from Cloud Use Teleport's Fetch from Cloud feature to pre-load the shortlisted entries for each category before judging begins. Entries arrive with all metadata intact -- category, entrant, agency, brand, country. The jury room now has everything locally.

3. Jury browses and searches entries locally The judging app queries Teleport's local search API to filter entries by category, subcategory, or entrant -- no internet required:

curl -X POST "http://localhost:8080/api/v1/assets/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "", "filters": {"category": "Film Craft"}, "sort": "entrant", "size": 50}'

Sub-10ms response times. Judges navigate entries without waiting.

4. Instant video playback from local hardware Film and case study entries stream directly from Teleport -- no buffering, no cloud round-trip:

curl "http://localhost:8080/api/v1/assets/{id}/transcodes/1080p-video.mp4"

For print and digital entries, the conversions endpoint serves high-res previews locally:

curl "http://localhost:8080/api/v1/assets/{id}/conversions?resize=2560,1400&format=jpg"

5. Scoring and deliberation via share pages (when connected) When venue connectivity permits, Teleport's cloud pass-through enables branded share pages for formal scoring. Create per-category share pages with the "Confidential Review" template -- jurors approve or reject entries with notes, and the jury president tracks progress through analytics. If connectivity drops, local browsing and playback continue uninterrupted.

6. Sync winners and archive to Cloud After judging concludes, sync winning entries and the full shortlist to FileSpin Cloud. The automation stack activates: AI agents assemble press kits, workflow engines trigger winner notifications, and branded share pages deliver clean originals to winners and press teams. Configure preservation rules so award entries survive local cleanup.

Upgrading Teleport​

Dashboard upgrade (recommended)​

When a new version is available, Teleport shows an upgrade banner on the dashboard. Click Upgrade Now -- Teleport backs up the database and previous binary, downloads the new version, and restarts automatically. Typically under 30 seconds of downtime.

Best practices​

1. Use SSD for hot folder and staging. File watcher performance and upload throughput scale directly with disk I/O speed. Putting hot folder and staging on the same SSD drive avoids cross-device moves.

   1. Set file_stability_wait for network drives. If your hot folder is on a NAS or network share, files may still be writing when detected. A 30-second stability wait prevents partial uploads (more details are in the Operation Guide).

2. Size the queue for your peak volume. Default is 10,000. Event venues processing 20,000+ assets in a day should increase queue_size to 50,000 (more details are in the Operation Guide). Attractions with continuous capture may need more.

3. Use preservation rules for critical assets. Archived assets are auto-purged based on retention settings. Tag hero images, purchased guest photos, or award entries as preserved so they survive cleanup.

4. Configure selective sync rules. Not every locally processed asset needs cloud backup. Sync purchased photos, approved assets, or a percentage -- reduces bandwidth and cloud storage costs by 80%+.

5. Run the benchmark before deployment. teleport --benchmark --headless gives you concrete performance numbers for your specific hardware. Use the results for capacity planning and to validate that your edge hardware meets throughput requirements.

Every team that works with external stakeholders hits the same bottleneck: getting the right assets to the right people in the right format, with some control over what happens next. The standard workflow — zip a folder, upload to WeTransfer, email a link, hope they download the right version — breaks down the moment you need tracking, branding, feedback, or approval.

Branded share pages replace that cycle. A share creates a branded, hosted page with a curated set of assets — configurable download options (including social media sizes), password protection, expiry dates, feedback collection, approval workflows, and full analytics on who viewed and downloaded what. No FileSpin account required for recipients.

Event teams use shares to deliver sponsor packages same-day. Wholesale teams use them as partner portals with controlled formats. Press teams use them for embargoed content with watermark protection. Attractions operators use them for guest photo discovery. And AI agents can assemble any of these from a single prompt.

This guide covers how to create and manage shares — from the Dashboard, through AI agents, or via workflow automation — plus real-world recipes for common distribution patterns.

Creating shares from the Dashboard​

The fastest way to create a share is directly from the FileSpin Dashboard. Select one or more assets, click Share, and configure the options.

Share settings​

When creating a share, you configure:

The share page​

Once created, you get a branded URL that recipients open directly — no login, no account, no software to install.

Recipients see a clean, branded page with your logo and colors. Depending on your settings, they can browse assets, leave comments, approve or reject individual items, and download in the formats you've made available.

Creating shares with AI agents​

FileSpin's MCP integration lets AI agents create shares through natural language. Instead of manually selecting assets and configuring settings, describe what you need:

"Find all photos tagged 'Gold Sponsor - Acme Corp' from Day 1 of the conference, create a branded share page with our event branding and password protection, and give me the link."

The agent searches your library, filters by tags, creates the share with your branding template, and returns the URL — all from a single prompt.

Common agent-driven share workflows:

• Sponsor delivery: "Create share pages for each sponsor from yesterday's event, branded with our event logo, password-protected, expiring in 30 days."
• Client review: "Share the latest hero images with the client for approval. Enable feedback and watermark everything."
• Press kit: "Assemble a press kit with the five approved product shots and the launch video. Watermark it, set a 7-day expiry."

For setup details, see the AI Agent Integration guide.

Creating shares with workflow engines - COMING SOON​

Workflow engines like Make, Zapier, and n8n can create shares automatically based on triggers — new assets uploaded, tags applied, approval status changed.

Example: Auto-create sponsor share in Make A Make scenario watches for assets tagged with a sponsor name. When the batch is complete (triggered by a "batch complete" tag or a scheduled check), the scenario creates a branded share page with the sponsor's assets, applies the event branding template, and sends the share URL via email to the sponsor contact.

Example: Post-approval delivery in n8n An n8n workflow monitors approval status. When all assets in a collection are approved, the workflow creates a clean (unwatermarked) share with high-res download options and notifies the client that final deliverables are ready.

Share features​

Branding​

Every share page can carry your brand identity — logo, colors, and background. Set these per share, or save them as part of a template to reuse across all your distribution workflows.

Watermark protection​

Enable watermarks to overlay your account watermark on all image and video previews and downloads. Useful during review phases — watermarks deter screenshot-based theft and signal that assets aren't final. Switch to clean downloads for final delivery.

Download options​

Control exactly what recipients can download:

With ODI (On-Demand Imaging) enabled, recipients can download images in any size — including social media dimensions — directly from the share page.

Feedback and comments​

Enable comments so reviewers provide feedback directly on shared assets. Reviewers access the share link and submit comments — no authentication required. Comments can be attached to specific assets or left at the share level. Reviewers optionally provide their name and email.

Approval workflows​

For formal review processes, enable approvals so reviewers can approve or reject individual assets with notes. The share owner sees approval status per asset — approved, rejected, or pending — along with reviewer comments and timestamps.

This powers the review-revise-deliver cycle: share watermarked assets for review, collect approvals, fix rejected items, re-share if needed, then deliver clean originals once approved.

Analytics​

Every share automatically tracks engagement.

Analytics provide proof of delivery for contractual obligations, and help you understand how recipients engage with your content.

Share templates​

If you create shares with the same settings repeatedly, templates save time and ensure consistency. FileSpin provides 8 ready-to-use preset templates:

Add any preset to your account from the Dashboard, or create custom templates with your own branding, download options, and workflow settings. Set a default template so it's pre-selected when creating new shares.

Recipe: Event sponsor delivery​

A multi-day conference generates thousands of photos. Each sponsor tier is contractually entitled to branded imagery delivered within 24 hours. The old way: someone manually hunts through folders, zips files, uploads to WeTransfer, and emails the link. No tracking, no branding, no proof of delivery.

1. Tag assets by sponsor during capture Photographers tag assets by session and sponsor — either manually or through AI auto-tagging after upload. Search surfaces all assets tagged for a specific sponsor.

2. Create a branded share per sponsor From the Dashboard, select the sponsor's assets and create a share using your event branding template. Set a password, configure download options (high-res originals plus social-ready ODI sizes for images, 1080p and 720p for video), and set an appropriate expiry.

Or let an AI agent do it: "Find all photos tagged 'Gold Sponsor - Acme Corp' from Day 1, create a branded share page with our event branding, password-protect it, and send me the link."

Or automate it: a Make/Zapier scenario watches for the "batch complete" tag and creates the share automatically.

3. Send the link to the sponsor The sponsor receives a branded page with the event's identity, password-protected, with download options for both high-res originals and social-ready sizes. No account needed.

4. Track delivery and engagement Check analytics to confirm the sponsor accessed the package — views, downloads by format, and timestamps. This is your proof of delivery for the contract.

Recipe: Wholesale partner portal​

An eCommerce brand needs to get product imagery to wholesale partners and buying teams — with controlled formats, no originals, and brand-compliant downloads.

1. Set up a wholesale template Create a share template configured for wholesale distribution: ODI enabled so partners can download in any size they need, but originals excluded — the brand controls the maximum resolution. No feedback or approval (this is delivery, not review). 90-day expiry matches the seasonal buying cycle.

2. Create a share per partner for each collection From the Dashboard, select the seasonal collection and create a share using the wholesale template. Add a password for each partner.

Or automate it: when assets in a collection are tagged "wholesale-ready," a workflow engine creates the share and emails the link to the partner contact from your CRM.

3. Monitor partner engagement Analytics tell you which partners downloaded, what formats they chose, and when — useful for follow-up and forecasting. A partner who hasn't viewed the share a week after receiving it might need a nudge.

Recipe: Press kit with watermark protection​

A pre-launch or embargoed press kit needs watermark protection during the embargo period, then clean downloads after the announcement.

Phase 1: Embargoed preview (watermarked) Create a share with watermarks enabled, password protection, and feedback enabled. Journalists can preview and provide feedback, but all downloads carry the watermark — protecting against premature publication. Set the expiry to the embargo date.

Phase 2: Post-announcement (clean downloads) After the embargo lifts, create a new share with the same assets — this time with watermarks disabled, originals included, and a longer expiry. Delete or let the embargoed share expire. Journalists now download clean, high-res assets for publication.

An AI agent can handle the transition: "The embargo lifted — create a clean press kit share with full downloads for the product launch assets, and revoke the embargoed share."

Recipe: Client review cycle with approvals​

A creative agency sends campaign assets to a client for approval. The client needs to approve or reject individual assets with feedback, and the agency needs to track the process.

1. Create the review share From the Dashboard, select the campaign assets and create a share with the "Feedback & Approval" template. Watermarks protect assets during review. The client receives a branded link — no account needed.

2. Client reviews and approves/rejects The client opens the share link and approves or rejects each asset with notes. Watermarks protect assets during the review phase.

3. Check the results The Dashboard shows approval status per asset, reviewer comments, and engagement analytics — did the client actually view the share? Which assets did they spend time on?

4. Revise and re-share Fix rejected assets based on feedback. Create a new share with the revised assets for another round of approval.

5. Deliver approved assets Once all assets are approved, create a "High-Res Downloads" share with clean (unwatermarked) originals for final delivery. The client downloads the approved assets in the formats they need.

Recipe: Awards event judging​

A creative awards festival receives thousands of entries across dozens of categories — film, print, digital, experiential. Jury panels need to shortlist remotely before the festival, then review and score on-site at the venue where Wi-Fi is unreliable and video entries need instant playback. The old way: USB drives passed between jury rooms, spreadsheets emailed between coordinators, and no audit trail of who scored what.

1. Organize entries by category Define an asset schema for awards entries — category, subcategory, entrant, agency, brand, country, and supporting case study fields. Upload entries and assign metadata during intake. Each category becomes a collection. AI auto-tagging accelerates classification for large entry volumes.

2. Remote shortlisting round Before the festival, create per-category share pages for each jury panel using the "Confidential Review" template — watermarked previews, feedback and approval enabled, password-protected, 14-day expiry. Jurors receive a branded link and score entries individually without needing a FileSpin account. Analytics track which jurors have reviewed and which haven't — useful for deadline reminders. Typically around ten percent of entries make the shortlist.

3. On-site judging at the venue Deploy Teleport at the festival venue for reliable local asset delivery. Jury rooms get instant playback of video entries and high-res image viewing from local hardware — no dependency on venue Wi-Fi. When connected, cloud pass-through enables the full share page experience with live feedback. Create fresh share pages for each jury room with just the shortlisted entries for their category.

4. Calibrate and award metals Jury presidents review shortlist results in the Dashboard — approval status, reviewer comments, and engagement analytics per entry. Working from the shortlist, juries decide which entries deserve Bronze, Silver, or Gold. Create a new share page with the medal-worthy subset for final deliberation. It takes a two-thirds majority vote to be awarded.

5. Grand Prix selection and winner delivery From the Gold winners, the jury selects the Grand Prix — the best in show. Create "High-Res Downloads" shares with clean originals for winners, press kits, and festival archives. Analytics provide a complete audit trail of the judging process — who viewed what, when they scored, and how the shortlist narrowed to the final winners.

Or let an AI agent handle the logistics: "Find all Gold winners in the Film category, create a branded press kit share with our festival branding, watermarked, password-protected, expiring in 30 days — and a separate clean share for the winners with full downloads."

Programmatic access​

For teams that need to create and manage shares programmatically, the full Shares API is available. The API supports everything described in this guide — creating shares, configuring branding and download options, enabling feedback and approvals, retrieving analytics, and managing templates.

Best practices​

1. Use templates for consistency. Create templates for your common workflows (sponsor delivery, wholesale portals, press kits, client review) so every share follows the same branding and settings.

2. Set appropriate expiry dates. 7–14 days for reviews, 30 days for deliverables, 90 days for partner portals. Don't let shares linger indefinitely.

3. Watermark during review, not delivery. Use watermarked downloads during the review phase to protect assets, then switch to clean downloads for final delivery.

4. Use password protection for sensitive content. Pre-launch materials, embargoed content, and confidential assets should be password-protected.

5. Check analytics before following up. Before chasing a client, check analytics to see if they've actually viewed the share. A "haven't reviewed yet" follow-up hits differently when you know they opened the page three times.

6. Let AI agents assemble shares. For ad-hoc distribution — "find all keynote photos, create a branded share for the press team" — an AI agent can search, filter, and create the share in a single prompt. See the AI Agent Integration guide.

7. Clean up expired shares. Periodically review and delete shares that are no longer needed.

FileSpin offers three automation paths: AI agents for ad-hoc, complex workflows through natural language; workflow engines for repeatable, visual pipelines operations teams build without engineering; and REST APIs for custom, high-throughput integrations. All three paths share the same asset lifecycle described in this guide.

FileSpin is an AI-native digital asset management platform used by eCommerce retailers, event producers, attractions operators, and media companies to manage, transform, and deliver assets autonomously. Whether you're syncing product photos from a photoshoot to multiple marketplaces, processing thousands of event images for sponsor delivery, capturing guest photos at attractions, or delivering media to global audiences -- understanding the asset lifecycle is essential for building integrations that scale.

Every integration with FileSpin follows the same fundamental pattern: get content in, let FileSpin process it, then serve it to your users. This guide walks through the entire pipeline so you can build a reliable, production-ready integration from day one.

How the pipeline works​

When you upload a file to FileSpin, it moves through a series of stages before it's ready to serve. Understanding this pipeline is essential for building integrations that handle timing correctly and don't surprise your users with missing thumbnails or incomplete metadata.

1. Upload -- You send the file (or a URL to fetch it from). FileSpin returns an asset ID immediately.
2. Storage -- The original file is saved to cloud storage (S3 or R2). A file-saved webhook fires.
3. Auto-processing -- Based on your account settings, FileSpin generates image conversions, video transcodes, and runs any enabled addons (auto-tags, face recognition, etc.). A file-processed webhook fires when complete.
4. Delivery -- The asset and its derivatives are available via CDN URLs for fast, global delivery.

Step 1: Upload an asset​

FileSpin supports two upload methods: direct multipart upload and URL ingest. Choose based on where your files originate.

Multipart upload (files you have)​

Use this when your application has the file -- a user-uploaded photo, a generated document, or a file from your server's filesystem.

curl -X POST "https://upload.filespin.io/api/v1/assets/new/content/original/upload" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -F "file=@product-photo.jpg"

Response:

{
  "assets": [
    {
      "id": "a1b2c3d4e5f6789012345678abcdef90",
      "status": "NOT_READY",
      "name": "product-photo.jpg",
      "size": 2456789,
      "checksum": "d41d8cd98f00b204e9800998ecf8427e",
      "content_type": "image/jpeg"
    }
  ]
}

You can upload multiple files in a single request by using file1, file2, etc. as form field names.

Attaching metadata at upload time​

You can include custom metadata in the same upload request. This is useful when your application has context about the file (e.g. which product it belongs to, who approved it, what campaign it's for):

curl -X POST "https://upload.filespin.io/api/v1/assets/new/content/original/upload" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -F "file=@product-photo.jpg" \
  -F 'custom_metadata={"data": {"project": "Summer Campaign", "status": "draft"}, "data_schema_id=1"}' 

data_schema_id is the optional ID of asset schema that powers custom searches and other powerful automations. See the post on Asset Schemas for more.*

URL ingest (files hosted elsewhere)​

Use this when the file already lives at a URL -- an image on a partner's CDN, a video on a content server, or an object in an S3 bucket.

curl -X POST "https://upload.filespin.io/api/v1/assets/new/content/original/external" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "interview.mp4",
    "key": "https://example.com/videos/interview.mp4"
  }'

For S3 objects, use the s3:// protocol:

curl -X POST "https://upload.filespin.io/api/v1/assets/new/content/original/external" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "interview.mp4",
    "key": "s3://my-bucket/path/to/file.mp4"
  }'

URL ingests are asynchronous -- FileSpin queues the download and returns a QUEUED status. The file will be fetched in the background.

The URL provided should allow direct downloads without any authorization. If S3 URL is provided, make sure the bucket is accessible for FileSpin (See Custom S3 Storage Setup in the docs).

Step 2: Check asset status​

After upload, the asset status is NOT_READY while the file is being saved to storage. You need to wait for it to become OK before performing further operations.

Polling for readiness​

curl "https://app.filespin.io/api/v1/assets/a1b2c3d4e5f6789012345678abcdef90/data" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY"

Response when ready:

status will be OK

{
  "id": "a1b2c3d4e5f6789012345678abcdef90",
  "status": "OK",
  "name": "product-photo.jpg",
  "size": 2456789,
  "content_type": "image/jpeg",
  "metadata": {
    "width": 4000,
    "height": 3000
  },
  "conversions": {},
  "addons_info": {
    "ON_DEMAND_IMAGE": {
      "available": true
    }
  }
}

Timing guidelines:

Using webhooks instead of polling​

Polling works for simple integrations, but webhooks are more efficient at scale. Configure a webhook URL in your account settings to receive file-saved notifications automatically. See the Webhooks in Integrations docs for the complete setup.

Step 3: Understand auto-processing​

Once the file is saved, FileSpin automatically processes it based on your account settings. This includes:

• Image conversions -- Smart imaging for on-demand transformations (ODI)
• Video transcodes -- Multiple resolutions (360p, 480p, 720p, 1080p) and HLS adaptive streaming
• Addons -- Auto-tags, face recognition, etc

Triggering processing manually​

If you need specific processing that isn't enabled by default, or you want to reprocess an asset:

curl -X POST "https://app.filespin.io/api/v1/assets/a1b2c3d4e5f6789012345678abcdef90/process" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["smart_imaging", "720p-video", "1080p-video", "hls-video"]
  }'

Refer to the Asset Processing docs for all the valid processing keys that can be used.

For video processing, the response includes a job_id that you can use to track progress. Processing completion is also notified via webhooks.

Step 4: Serve assets via CDN​

Once processing is complete, your assets are ready for delivery through FileSpin's global CDN.

Serving images with on-demand transformations​

Once ON_DEMAND_IMAGE processing is complete (usually within a second or two), you can serve images with real-time transformations via URL parameters:

https://cdn.filespin.io/api/v1/assets/ASSET_ID/conversions?resize=800,600&quality=85

This resizes to 800x600 and compresses to quality 85 -- all on the fly, cached at the CDN edge.

See the Image Transformations Docs for the full transformation reference.

Serving video transcodes​

Video transcodes are available through the get_link API:

curl "https://app.filespin.io/api/v1/assets/ASSET_ID/get_link?key=720p-video&link_type=cdn&delivery=display" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY"

The response includes a signed CDN URL you can use directly in a video player or embed tag:

{
  "url": "https://cdn.filespin.io/api/v1/assets/ASSET_ID/transcodes/720p-video.mp4?expiry=..."
}

For public videos, you can also construct the URL directly: https://cdn.filespin.io/api/v1/assets/ASSET_ID/transcodes/720p-video.mp4

Public vs. private assets​

By default, assets are private except for on-demand images. Private files require authentication to access. For public-facing content, you can make individual assets public using the set_public_access API:

curl -X POST "https://app.filespin.io/api/v1/assets/ASSET_ID/content/set_public_access" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["original", "720p-video"]
  }'

For private assets that need temporary access (e.g. serving to authenticated users on your website), use the get_link API with signed URLs:

curl "https://app.filespin.io/api/v1/assets/ASSET_ID/get_link?key=original&expiry=3600" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY"

This returns a signed URL valid for 3600 seconds (1 hour). FileSpin checks the signature and expiry before serving the file.

Replacing asset content​

Sometimes you need to update the file while keeping the same asset ID -- for example, when a designer revises a photo but you want to preserve all the metadata and the reference in your application.

curl -X POST "https://upload.filespin.io/api/v1/assets/ASSET_ID/content/original/replace" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -F "file=@updated-product-photo.jpg"

The asset ID stays the same, but the content is replaced. All conversions and transcodes will be regenerated based on accoount settings.

Error handling​

Common status values​

Handling errors in the asset data​

When something goes wrong, the errors field in the asset data provides details:

{
  "id": "a1b2c3d4e5f6789012345678abcdef90",
  "status": "ERROR",
  "errors": {
    "original": "Original file appears to be invalid!"
  }
}

Warnings (non-fatal issues) are also reported:

{
  "errors": {
    "warning": "This may be a PNG file uploaded as JPG!"
  }
}

Putting it all together​

Here's a complete Python example that uploads an image, waits for it to be ready, and builds a CDN URL for serving:

import requests
import time

API_KEY = "YOUR_API_KEY"
API_BASE = "https://app.filespin.io/api/v1"
UPLOAD_BASE = "https://upload.filespin.io/api/v1"  # upload, ingest and replace use the upload host
CDN_BASE = "https://cdn.filespin.io/api/v1"
HEADERS = {"X-FileSpin-Api-Key": API_KEY}

# 1. Upload the file
with open("product-photo.jpg", "rb") as f:
    resp = requests.post(
        f"{UPLOAD_BASE}/assets/new/content/original/upload",
        headers=HEADERS,
        files={"file": f}
    )
asset_id = resp.json()["assets"][0]["id"]
print(f"Uploaded: {asset_id}")

# 2. Wait for asset to be ready
for _ in range(30):
    resp = requests.get(
        f"{API_BASE}/assets/{asset_id}/data",
        headers=HEADERS
    )
    data = resp.json()
    if data["status"] == "OK":
        break
    time.sleep(1)
else:
    raise TimeoutError("Asset did not become ready in time")

# 3. Build a CDN URL with transformations
thumbnail_url = (
    f"{CDN_BASE}/assets/{asset_id}/conversions"
    f"?resize=400,300&quality=80"
)
print(f"Thumbnail URL: {thumbnail_url}")

Best practices​

1. Store the asset ID in your application database right after upload. This is your permanent reference to the file in FileSpin.

2. Use webhooks over polling for production systems. Polling is fine for development, but webhooks scale better and react faster.

3. Check status before operating on an asset. Never assume an upload is instantly available.

4. Use on-demand transformations for images instead of pre-generating every size. This saves storage and processing time.

5. Enable auto-processing for videos in your account settings for the transcodes you regularly need, so every video upload is processed for transcodes automatically.

Every asset in FileSpin has core metadata -- file name, size, content type, dimensions. But real-world asset management needs more. You need to track which campaign a photo belongs to, who approved it, what product SKU it represents, or when the usage rights expire.

Asset schemas let you define structured metadata fields for your assets, with validation, search indexing, and UI rendering -- all powered by JSON Schema standard.

What is an asset schema?​

An asset schema is a JSON Schema definition that describes the custom metadata fields you want to attach to assets. Think of it as a form definition: it specifies the fields, their types, validation rules, and how they should be displayed and searched.

Schema = field definitions + validation rules + search configuration + UI hints

When you assign a schema to an asset and provide data, FileSpin:

• Validates the data against the schema before saving
• Indexes searchable fields for fast retrieval
• Renders form fields in dashboard using the UI hints

Real-World Use Cases​

Asset schemas solve critical metadata challenges across industries:

• eCommerce — Track SKU, product name, category, seasonal tags, usage rights, and approval status for every product image. Schemas enable fast search-to-shelf workflows and enforcement of channel-specific metadata before syndication to Amazon, Shopify, and marketplace partners.
• Events & Conferences — Capture speaker name, session ID, sponsor affiliation, and usage rights for event photography. Face recognition pairs with metadata for automatic speaker identification, and schemas enable filtered sponsor asset delivery through branded share pages.
• Attractions & Experiences — Tag photos with guest ID, ride, location, and timestamp. Schemas power unified guest galleries ("find all my photos") and drive preview-to-purchase revenue workflows.
• Real Estate — Organize property images by listing ID, room type, and status. Schemas enable automatic portal-specific format generation and off-market watermark protection.

Getting started with preset schemas​

FileSpin provides industry-specific preset schemas so you don't have to start from scratch. These cover the most common metadata patterns for different use cases.

List available presets​

Available presets:

Using presets​

Presets are available for immediate use. To apply a preset to your assets, reference the preset ID when creating a schema or assigning metadata. For example, use ecommerce to tag assets with product-specific fields like SKU, category, and season.

Each preset includes a set of common fields (title, description, tags, status, project, etc.) plus industry-specific fields. You can customize them after creation by building a custom schema based on the preset structure.

Designing a custom schema​

If presets don't fit your needs, you can design a schema from scratch. Here's the anatomy of a schema definition:

Schema structure​

{
  "name": {"en": "Product Assets"},
  "status": "ACTIVE",
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "product_name": {
        "type": "string",
        "maxLength": 200,
        "filespin_properties": {
          "title": {"en": "Product Name"},
          "hint": {"en": "The product this asset is associated with"},
          "placeholder": {"en": "e.g. Summer Hat Collection"},
          "searchable": true,
          "keyword_searchable": true,
          "ui": {"order": 1}
        }
      },
      "sku": {
        "type": "string",
        "maxLength": 50,
        "filespin_properties": {
          "title": {"en": "SKU"},
          "searchable": false,
          "keyword_searchable": false,
          "ui": {"order": 2}
        }
      }
    }
  }
}

Supported field types​

String fields:

"title": {
  "type": "string",
  "maxLength": 500
}

String with format (email):

"contact_email": {
  "type": "string",
  "format": "email",
  "maxLength": 254
}

Date fields:

"expiration_date": {
  "type": "string",
  "format": "date"
}

Date values must be in YYYY-MM-DD format.

Enum fields (predefined options):

"status": {
  "type": "string",
  "enum": ["draft", "in_review", "approved", "published", "archived"]
}

Array fields (multiple values):

"tags": {
  "type": "array",
  "items": {"type": "string", "maxLength": 100}
}

Number fields:

"price": {
  "type": "number"
}

Boolean fields:

"approved": {
  "type": "boolean"
}

FileSpin properties​

Every field should include filespin_properties to control how it behaves in search and the UI:

"filespin_properties": {
  "title": {"en": "Display Label"},
  "hint": {"en": "Help text shown below the field"},
  "placeholder": {"en": "Placeholder text inside the input"},
  "searchable": true,
  "keyword_searchable": true,
  "ui": {
    "order": 1,
    "readonly": false,
    "disabled": false,
    "hidden": false,
    "multiline": false
  }
}

Creating a schema​

Use the Create Asset Schema API:

curl -X POST "https://app.filespin.io/api/v1/assetschemas" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": {"en": "Product Assets"},
    "status": "ACTIVE",
    "schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "product_name_txt": {
          "type": "string",
          "maxLength": 200,
          "filespin_properties": {
            "title": {"en": "Product Name"},
            "searchable": true,
            "keyword_searchable": true,
            "ui": {"order": 1}
          }
        },
        "sku": {
          "type": "string",
          "maxLength": 50,
          "filespin_properties": {
            "title": {"en": "SKU"},
            "searchable": false,
            "ui": {"order": 2}
          }
        },
        "category": {
          "type": "string",
          "enum": ["clothing", "accessories", "footwear", "electronics"],
          "filespin_properties": {
            "title": {"en": "Category"},
            "searchable": false,
            "ui": {"order": 3}
          }
        },
        "tags": {
          "type": "array",
          "items": {"type": "string", "maxLength": 100},
          "filespin_properties": {
            "title": {"en": "Tags"},
            "searchable": true,
            "keyword_searchable": true,
            "ui": {"order": 4}
          }
        }
      }
    }
  }'

Response:

{
  "id": 3
}

Assigning a schema to an asset​

At upload time​

Include data_schema_id and custom_metadata in the upload request:

curl -X POST "https://upload.filespin.io/api/v1/assets/new/content/original/upload" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -F "file=@summer-hat.jpg" \
  -F 'custom_metadata={"product_name": "Summer Straw Hat", "sku": "HAT-STR-001", "category": "accessories", "tags": ["summer", "straw", "beach"], data_schema_id=3}'

After upload (update metadata)​

curl -X POST "https://app.filespin.io/api/v1/assets/ASSET_ID/data/update" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data_schema_id": 3,
    "data": {
      "product_name": "Summer Straw Hat",
      "sku": "HAT-STR-001",
      "category": "accessories",
      "tags": ["summer", "straw", "beach"]
    },
    "mode": "REPLACE"
  }'

FileSpin validates the data against the schema before saving. If validation fails, a HTTP 400 response will be returned with useful error message.

Using schemas with the File Picker widget​

When using the File Picker widget, assign a schema via the reserved __data_schema_id key:

var payload = {
  "ASSET_ID": {
    "product_namet": "Summer Straw Hat",
    "sku": "HAT-STR-001",
    "__data_schema_id": 3
  }
};

The __data_schema_id key is not stored as data -- it only tells FileSpin which schema to associate.

Searching by schema fields​

Once assets have schema data, you can search using schema_criteria:

curl -X POST "https://app.filespin.io/api/v1/assets/search" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_criteria": {
      "data_schema_id": 3,
      "fields": {
        "category": "accessories",
        "tags": "summer"
      }
    }
  }'

You can combine schema criteria with keyword search and other filters:

curl -X POST "https://app.filespin.io/api/v1/assets/search" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "hat",
    "content_type": "image*",
    "schema_criteria": {
      "data_schema_id": 3,
      "fields": {
        "category": "accessories"
      }
    }
  }'

See the Search Patterns guide for more advanced search techniques.

Updating a schema​

Use the Update Asset Schema API to modify schemas. You can change some things, but with restrictions to protect existing data:

What you CAN change​

• Add new fields -- Existing assets won't have values for these fields, which is fine
• Increase maxLength for text fields -- Makes the field accept longer values

What you CANNOT change​

• Field types -- Can't change a string to a number
• Search properties (searchable, keyword_searchable) -- Would require re-indexing
• Remove fields -- Would orphan existing data
• Rename fields -- Same as remove + add, breaks existing data
• Decrease minLength -- Would invalidate previously valid data

Deleting a schema​

Use the Delete Asset Schema API. Schemas can be deleted directly. To deactivate a schema instead (soft-delete), set its status to INACTIVE:

# Delete the schema
curl -X DELETE "https://app.filespin.io/api/v1/assetschemas/3" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY"

Alternatively, to keep the schema but prevent new assets from using it, set it to INACTIVE:

curl -X PUT "https://app.filespin.io/api/v1/assetschemas/3" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 3, "status": "INACTIVE", "name": {"en": "Product Assets"}, "schema": {"$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}}}'

Best practices​

1. Use presets as a starting point. Even if they don't match your use case exactly, they demonstrate good schema design patterns and save time.

2. Keep total metadata under 3,000 characters. This is the storage limit per asset for custom data. Avoid storing lengthy content -- keep metadata concise and descriptive.

3. Keep individual text fields under 1,000 characters. This is the per-field limit for string values.

4. Start with common fields. Fields like title, description, tags, and status are useful in almost every schema. The presets all share 11 common fields for this reason.

5. Use enums for controlled vocabularies. If a field has a fixed set of valid values (status, category, region), use enum to enforce consistency.

6. Configure search properties deliberately. Making every field searchable and keyword_searchable adds indexing overhead. Only enable what you actually need to query.

A conference produces thousands of photos, and the speaker's agent wants every one with the speaker in it by the end of the day. An attraction captures guests on rides, at meet-and-greets and from roaming photographers, and the guest wants all of their photos, not the three they happen to remember. File names and tags do not help with either: nobody tags a photo with the names of the people in the background.

FileSpin's Face Recognition addon indexes the faces in your images. After that, one reference photo finds every indexed image with that person in it, and the search can be narrowed with your own metadata, such as event, day or location. This guide covers turning indexing on, searching by face from the Dashboard, an AI agent and the API, and what happens to face data.

How it works​

Face recognition has two halves:

• Indexing detects up to 10 faces in an image and stores an embedding for each: a set of numbers that describes the face, not a copy of it. The asset's _filespin_fr_count metadata field records how many faces were found. Indexing runs in the background.
• Searching takes the most prominent face in a reference photo, compares it with the indexed faces in your account and returns the matching assets. The reference photo is discarded when the search completes.

Only indexed images can be found, so indexing comes first.

Step 1: Index your images​

Index automatically on upload​

For most accounts, the right setup is to index every new image as it arrives. Admins and managers set this up in the Dashboard:

1. Open Admin → Add-ons.
2. On the Face Recognition and Search card, turn the addon on.
3. Select the gear icon to open the trigger settings.
4. Enable When asset is saved to index each new upload. When asset metadata is updated indexes an asset when its metadata changes instead.
5. Optionally, add schema field conditions so only relevant assets are indexed, such as assets whose event field is set. Narrower conditions mean fewer images processed and fewer credits used.

Leave Process derived assets off unless you want FileSpin-generated outputs, such as background-removed copies, indexed as well. Otherwise the same face is indexed twice.

The same trigger settings are available through the Update Addons Settings API. That call replaces the account's whole addon configuration, so send every addon's current settings along with the change.

Index images you already have​

Triggers only act on new events, so images uploaded before you turned indexing on need indexing separately:

• In the Dashboard, the Reprocess Assets page (admins and managers) takes a comma-separated list of asset IDs and the addons to run on them. Tick Face Recognition.
• With the API, queue each image with Index Faces:

curl -X POST "https://app.filespin.io/api/v1/assets/ASSET_ID/addons/face_recognition" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disposition": {"update_metadata": true}}'

The response is HTTP 202 with an empty body: the image is queued. HTTP 409 means the asset is already indexed. Face Index Status reports QUEUED, PROCESSING, DONE or ERROR for about a day after the request.

To find images that are already indexed, run an asset search with "addons_criteria": ["FACE_RECOGNITION"], or tick Face Recognition under Addons Processed in the Dashboard filter panel.

Step 2: Search by face​

In the Dashboard​

When the addon is enabled, the search bar on the Assets page shows a face icon.

1. Select the face icon.
2. Take a photo with your camera, or select Browse from files to pick a JPEG or PNG reference photo.
3. To narrow the search, pick a schema under Filters, fill in the fields to match (for example, the event and day) and select Submit.

Matches appear in the normal asset grid with a Face search active pill. Keyword search, sorting and the regular filter panel are off while a face search is active. Remove the reference photo from the search bar to return to normal search.

With an AI agent​

The search_by_face tool on the FileSpin MCP Server takes the reference face in three ways: an image already in FileSpin (by asset ID), a photo shared in the conversation, or a public image URL. Photos passed in the conversation or by URL are not stored.

• "Use asset 9f2c… as the face reference and find every photo of this person from the Lisbon summit."
• "Here is a photo of our keynote speaker. Find all matching photos, add them to a collection called Keynote – Day 1 and create a share page for the speaker's team."
• "Find all photos of this guest from today, then build a gallery share that expires in 7 days."

The second and third prompts show where an agent earns its keep: it chains the face search with tagging, collections and Branded Share Pages, which would otherwise be several manual steps.

With the API​

Face Search is a multipart form upload:

curl -X POST "https://app.filespin.io/api/v1/ml/people/facesearch" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -F "image=@reference-photo.jpg" \
  -F "strictness=9.5" \
  -F 'filters={"event": "lisbon-summit", "day": "1 2"}'

{
  "data": {
    "matches": [
      "a1b2c3d4e5f6789012345678abcdef90",
      "b2c3d4e5f6789012345678abcdef901a"
    ]
  },
  "page": 1,
  "search_id": "eed4c602a80a4920a4a9e56b5d3ea161",
  "limit_per_page": 30,
  "hits": 2
}

Strictness trades recall for precision. The default of 9.9 returns only close matches. If you know a person is in photos that are not being found, lower it in small steps, such as 9.5 and then 9.0, and check the extra results for look-alikes as you go.

Filters narrow matches by asset metadata:

• Fields are ANDed together. Field names are case-sensitive.
• Space-separated values in one field are ORed: {"day": "1 2"} matches day 1 or day 2.
• Fields whose names end in Date take an inclusive ISO 8601 range: {"captureDate": ["2026-03-01T00:00:00Z", "2026-03-03T23:59:59Z"]}.
• Filters need face recognition to be running from the addon's trigger settings (Step 1).

Paging through matches​

hits is the total number of matches. Later pages come from Paginated Search Results with the search_id:

curl "https://app.filespin.io/api/v1/ml/people/facesearch?search_id=eed4c602a80a4920a4a9e56b5d3ea161&page=2" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY"

The page request has its own limit_per_page (default 30) and extended_result (default false) parameters. They do not carry over from the first request, so send the same values on every page, or page numbers will not line up with the first page. A loop that reads every match:

import math
import requests

API_BASE = "https://app.filespin.io/api/v1"
HEADERS = {"X-FileSpin-Api-Key": "YOUR_API_KEY"}
PER_PAGE = 30

with open("reference-photo.jpg", "rb") as f:
    first = requests.post(
        f"{API_BASE}/ml/people/facesearch",
        headers=HEADERS,
        files={"image": f},
        data={"strictness": "9.5", "limit_per_page": str(PER_PAGE)},
    ).json()

matches = list(first["data"]["matches"])
for page in range(2, math.ceil(first["hits"] / PER_PAGE) + 1):
    resp = requests.get(
        f"{API_BASE}/ml/people/facesearch",
        headers=HEADERS,
        params={"search_id": first["search_id"], "page": page, "limit_per_page": PER_PAGE},
    )
    resp.raise_for_status()
    matches.extend(resp.json()["data"]["matches"])

print(f"{len(matches)} matching assets")

Face data and privacy​

You control how long face data is kept: it stays until you delete it, in one of two ways:

• When you delete an asset, FileSpin deletes its face data as part of the deletion. This applies to single and bulk deletes.
• On request, Delete Face Data removes the face data for up to 100 assets per call while keeping the assets themselves. Deletion is asynchronous (HTTP 202) and usually completes within seconds. This endpoint needs the admin role.

curl -X POST "https://app.filespin.io/api/v1/assets/addons/face_recognition/delete" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["a1b2c3d4e5f6789012345678abcdef90", "b2c3d4e5f6789012345678abcdef901a"]}'

Deleting face data keeps the _filespin_fr_count field, so the asset still shows how many faces it had. To index the asset again later, delete its face data first: indexing an asset that is already indexed returns HTTP 409.

You decide which images are indexed and are responsible for having the right to process the faces in them. Face Recognition Data Handling describes how FileSpin stores and protects face data.

Limitations​

• 10 faces per image are indexed. In crowd shots, some faces will not be.
• Image quality decides accuracy. Small faces (under about 40×40 pixels), strong angles, blur and harsh lighting all reduce matches. See Face Recognition Limitations.
• One face per search. If the reference photo has several people, only the most prominent face is used. Crop to the person you want.
• Indexing is asynchronous. A photo uploaded a moment ago may not be searchable yet.

Best practices​

1. Index on upload, with conditions. Automatic indexing keeps coverage complete. Schema conditions keep it to the images that need it, which keeps the credit spend proportional.

2. Use clear reference photos. A sharp, well-lit, front-facing photo of one person does more for results than any strictness setting.

3. Lower strictness only when you are missing known matches. Lower it in small steps and check what each step adds.

4. Record the facts you will filter on at upload. Event, day, venue and photographer in schema fields make face search filters possible. They are hard to add afterwards.

5. Delete face data you no longer need. When an event's photos have been delivered, delete the face data for those assets, even if you keep the images.

Next steps​

• Search patterns: combine metadata filters and paging with any search
• Branded Share Pages: deliver matched photos to speakers, sponsors or guests
• AI agent integration: chain face search with tagging, collections and shares
• Face Recognition API reference

A DAM that cannot find things is a storage bill. Retail teams look for every approved shot of one product line, event teams for last Tuesday's keynote photos, attractions for one day's captures at one ride. The asset is almost always there. The question is whether the search can narrow to it before someone gives up and asks a colleague.

FileSpin runs the same search behind the Dashboard, the AI agent and the REST API. A filter you set in one behaves the same in the others, so a search a marketer builds in the Dashboard is the search a developer later automates. This guide covers the criteria you can combine, how paging works, and the patterns that keep result sets small enough to be useful.

What you can search on​

Every search is a set of criteria. All criteria in one search are combined with AND: an asset must match every one.

Custom fields only become searchable when the schema says so. Mark a field searchable to filter on it, and keyword_searchable to have the keyword box match it too. The custom metadata schemas guide covers schema design.

Search in the Dashboard​

The Assets page is where most people search, and it exposes most of the criteria above without writing a query.

1. Type in the search bar for a keyword search. Results update as you type.
2. Open the filter panel with the sliders icon to add file name, content type, upload date, asset status, addons processed and asset schema filters. For a schema filter, pick the schema, fill in the fields you care about and select Submit.
3. Check the filter pills above the results. Every active filter shows as a pill you can remove, with Clear all to start again. If a search returns fewer assets than expected, a forgotten pill is the usual reason.
4. Sort with the Sort by menu: upload date, file name, content type or file size. Select the active option again to flip between ascending and descending. The default is newest upload first.
5. Page through results with the pager at the bottom. You can show 12, 18 or 30 assets per page.

Deleted assets do not appear in normal searches. Admins can search them on the Deleted Assets page, which has its own keyword search, sorting and content-type filter.

Search with an AI agent​

Through the FileSpin MCP Server, an agent turns a plain request into the same search criteria. When you use the agent inside the Dashboard, the filters it applies show up as the same pills, so you can see exactly what it searched for and adjust it by hand.

Prompts that work well name the criteria the way you would set them in the filter panel:

• "Find all PDFs uploaded in March with 'brand guidelines' in the file name."
• "Show the 10 most recent images where the campaign field is spring-2026 and status is approved."
• "Find images older than 18 months that have never been processed for auto-tags."
• "List every video uploaded last week, largest first."

Agents are good at the follow-up step that search alone does not do: tag the results, add them to a collection or build a Branded Share Page from them, in the same conversation.

Search with the API​

The Search API uses two calls:

1. POST /api/v1/assets/search runs the search and returns the first page plus a search_result_id.
2. GET /api/v1/assets/search/{search_result_id}/{page} returns later pages of the same search.

A request combines whichever criteria you need:

curl -X POST "https://app.filespin.io/api/v1/assets/search" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "summer",
    "content_type": "image*",
    "upload_time_range": {
      "start": "2026-01-01T00:00:00Z",
      "end": "2026-06-30T23:59:59Z"
    },
    "schema_criteria": {
      "data_schema_id": 3,
      "fields": {
        "category": "clothing",
        "status": "approved"
      }
    },
    "sort_by": ["upload_time_range_DESC"]
  }'

The response lists asset IDs for the first page:

{
  "status": "OK",
  "search_result_id": "0a9761f2f9",
  "result": [
    "a1b2c3d4e5f6789012345678abcdef90",
    "b2c3d4e5f6789012345678abcdef901a"
  ],
  "total_files": 47,
  "page": 1,
  "total_pages": 2
}

The full parameter list is in the Search API reference.

Keyword rules​

• OR or AND, not both. beach OR sunset matches either word. beach AND sunset matches both. A keyword cannot mix AND and OR, and is limited to 40 words.
• Exact phrases go in double quotes. To match ABC 123 as a phrase, send "\"ABC 123\"".
• Quote words with special characters. + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / have meaning in a query, so search for ABC-123 as "\"ABC-123\"".
• File names match on words of three or more characters. A file called IMG_04.jpg will not be found by keyword 04. Use the file_name criterion with a wildcard instead: IMG_04*.

Custom metadata​

schema_criteria matches values in fields your schemas mark as searchable. Values support the same OR, suffix wildcard (john*) and quoting rules, and number fields take a range:

{
  "schema_criteria": {
    "data_schema_id": 42,
    "fields": {
      "season": "spring OR summer",
      "sku": "SNK-24*",
      "rating": [4, 5]
    }
  }
}

Advanced Search Options has the full syntax.

Sorting​

sort_by takes a list of keys, each ending in _ASC or _DESC. The keys are upload_time_range, file_name, content_type and file_size_range. The first key is the primary sort and later keys break ties. Without sort_by, results come newest upload first.

Paging through results​

Each page holds up to 30 asset IDs (limit_per_page, 1 to 30). A few rules shape any code that reads more than one page:

• A search_result_id lasts 60 minutes. It stores the search criteria, not the results: each page request runs the search again, so newly uploaded assets can appear and page contents can shift. After 60 minutes the ID returns HTTP 410. Run the search again to get a new one.
• A search can page through 10,000 results at most. total_files can be higher than what total_pages lets you read. Split larger result sets with narrower criteria, such as one month of upload_time_range at a time.
• Pages can hold fewer IDs than limit_per_page. Assets the caller cannot access are left out of the page. Count pages, not IDs.
• Requesting a page past total_pages returns HTTP 400.

So loop over total_pages rather than comparing the number of IDs you have collected with total_files:

import requests

API_BASE = "https://app.filespin.io/api/v1"
HEADERS = {"X-FileSpin-Api-Key": "YOUR_API_KEY"}

first = requests.post(
    f"{API_BASE}/assets/search",
    headers=HEADERS,
    json={"content_type": "image*", "keyword": "product"},
).json()

asset_ids = list(first["result"])
for page in range(2, first["total_pages"] + 1):
    resp = requests.get(
        f"{API_BASE}/assets/search/{first['search_result_id']}/{page}",
        headers=HEADERS,
    )
    resp.raise_for_status()
    asset_ids.extend(resp.json()["result"])

print(f"{len(asset_ids)} of {first['total_files']} assets read")

Asset data in the results​

Set "extended_result": true to get the full Asset Data for every asset on the page, keyed by asset ID, alongside the result list. It saves a request per asset but makes the search slower. Use it when you are about to display or process the assets, and leave it off when you only need IDs.

Duplicates and the trash​

• GET /api/v1/assets/{asset_id}/content/original/duplicates returns the IDs of other assets whose original file has the same MD5 checksum, whatever their file names. See Find Duplicates.
• "trashed": true searches deleted assets that have not been purged yet. It needs the admin role.

Best practices​

1. Start from the narrowest criterion you have. A content type and an upload date range cut most libraries down faster than a longer keyword does.

2. Put the facts you filter on in schema fields. Status, campaign, SKU and season work better as searchable schema fields than as words in a file name. Exact values match exactly, and ranges work on numbers.

3. Turn keyword search on deliberately. Mark free-text fields such as descriptions keyword_searchable so the search bar finds them. Leave codes and statuses as plain searchable fields so a keyword search does not match them by accident.

4. Sort explicitly when order matters. Newest first is the default. If a report or export depends on order, send sort_by so the result does not change if the default ever does.

5. Partition anything over 10,000 results. Split by month or by content type and run each slice as its own search.

6. Ask for asset data only when you use it. extended_result is the right call for a page you are about to render, and wasted work for a job that only needs IDs.

Next steps​

• Custom metadata schemas: design fields that search well
• Face recognition: find people by face, not keyword
• AI agent integration: search and act on results in one conversation
• Search API reference

Why event-driven is essential for media workflows​

Media teams in eCommerce, events, attractions, and real estate rely on fast asset delivery. Polling the API to check if an asset has been processed, or scanning for new uploads, wastes resources and adds latency—and in high-volume environments, it simply doesn't scale. Webhooks flip the model: instead of your application asking FileSpin "anything new?", FileSpin tells your application the moment something happens. This is essential for retail teams launching seasonal campaigns, event organizers managing thousands of submissions under deadline, attractions maximizing preview-to-purchase conversion, and real estate teams publishing listings to multiple portals instantly.

This guide covers setting up webhooks, understanding the event types and payloads, and building reliable, event-driven integrations.

Why webhooks matter​

Without webhooks, a typical integration polls repeatedly:

With webhooks, FileSpin pushes events to your app the moment they happen:

Setting up webhooks​

Webhooks are configured in your FileSpin account settings. You specify one or more callback URLs to receive POST notifications when asset events occur.

Configure via Dashboard​

1. Navigate to Settings in your FileSpin Dashboard
2. In the Webhooks section, add your callback URL (e.g., https://your-app.com/webhooks/filespin)
3. Save your settings

You can configure multiple webhook URLs. FileSpin will POST to all configured URLs whenever an asset event occurs.

Webhook events​

FileSpin sends webhook callbacks for the following asset lifecycle events:

Event flow for a typical upload​

Upload ──> file-saved ──> file-processed

1. file-saved fires when the original file is stored. At this point, the asset has core metadata (name, size, content type, dimensions) but no conversions or transcodes yet.

2. file-processed fires when all automatic processing is complete. The asset now has its generated conversions, transcodes, and addon results.

For metadata updates:

Update data ──> file-data-updated

For deletion and restoration:

Delete ──> file-deleted ──> Undelete ──> file-undeleted

Webhook payload​

Standard events (file-saved, file-processed, file-data-updated, addon-processed)​

For these events, the webhook payload is the Asset Data Format — the same JSON structure returned by the Asset API. This includes:

{
  "id": "99d819953914402babbdeb68337ea6a3",
  "status": "OK",
  "name": "product-photo.jpg",
  "size": 2456789,
  "checksum": "d41d8cd98f00b204e9800998ecf8427e",
  "content_type": "image/jpeg",
  "creator_id": 42,
  "upload_time": "2026-02-17T10:30:00Z",
  "update_time": "2026-02-17T10:30:05Z",
  "metadata": {
    "width": 4000,
    "height": 3000
  },
  "data": {
    "product_name_txt": "Summer Straw Hat",
    "sku_s": "HAT-STR-001"
  },
  "conversions": {
    "720p-video": {
      "width": 1280,
      "height": 720,
      "size": 716000,
      "public": true
    }
  },
  "addons_info": {
    "ON_DEMAND_IMAGE": {
      "available": true
    }
  }
}

On-demand image (ODI) is available for assets after they are processed the first time. Availability is indicated by the ON_DEMAND_IMAGE key in addons_info.

Key fields to check:

Deletion events (file-deleted, file-undeleted)​

These events use a different payload format:

{
  "event": "file-deleted",
  "id": "99d819953914402babbdeb68337ea6a3",
  "keys": ["deepzoom"],
  "status": "OK",
  "message": ""
}

Example file-deleted with error:

{
  "event": "file-deleted",
  "id": "99d819953914402babbdeb68337ea6a3",
  "keys": ["deepzoom"],
  "status": "ERROR",
  "message": "S3 Permission denied",
  "errors": {
    "deepzoom": "S3 Permission denied"
  }
}

Building a webhook handler​

Here's a practical webhook handler that processes different events:

Python (Flask)​

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/filespin", methods=["POST"])
def handle_webhook():
    payload = request.get_json()

    # Deletion events include an "event" field
    event = payload.get("event")

    if event in ("file-deleted", "file-undeleted"):
        handle_deletion_event(payload)
    else:
        handle_asset_event(payload)

    return jsonify({"status": "ok"}), 200

def handle_asset_event(asset_data):
    """Handle file-saved, file-processed, file-data-updated, addon-processed."""
    asset_id = asset_data["id"]
    status = asset_data.get("status")
    name = asset_data.get("name")
    content_type = asset_data.get("content_type")

    if status == "NOT_READY":
        # file-saved: asset uploaded but not yet processed
        print(f"New asset saved: {name} ({content_type})")
        # db.assets.insert(asset_id=asset_id, name=name, status="processing")

    elif status == "OK":
        # file-processed: all conversions complete
        conversions = asset_data.get("conversions", {})
        urls = asset_data.get("urls", {})
        available_formats = list(conversions.keys())
        print(f"Asset processed: {asset_id}, formats: {available_formats}")
        # db.assets.update(asset_id, status="ready", formats=available_formats, urls=urls)

    elif status == "ERROR":
        errors = asset_data.get("errors", {})
        print(f"Processing failed for {asset_id}: {errors}")
        # db.assets.update(asset_id, status="error", errors=errors)

def handle_deletion_event(payload):
    """Handle file-deleted and file-undeleted."""
    asset_id = payload["id"]
    event = payload["event"]
    status = payload.get("status")
    keys = payload.get("keys", [])

    if event == "file-deleted":
        print(f"Asset deleted: {asset_id}, keys: {keys}, status: {status}")
        # db.assets.mark_deleted(asset_id)
    elif event == "file-undeleted":
        print(f"Asset restored: {asset_id}, keys: {keys}")
        # db.assets.mark_active(asset_id)

if __name__ == "__main__":
    app.run(port=5000)

Node.js (Express)​

const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhooks/filespin", (req, res) => {
  const payload = req.body;
  const event = payload.event;

  if (event === "file-deleted" || event === "file-undeleted") {
    handleDeletionEvent(payload);
  } else {
    handleAssetEvent(payload);
  }

  res.status(200).json({ status: "ok" });
});

function handleAssetEvent(assetData) {
  const { id, status, name, content_type } = assetData;

  if (status === "NOT_READY") {
    console.log(`New asset saved: ${name} (${content_type})`);
    // Insert into database
  } else if (status === "OK") {
    const formats = Object.keys(assetData.conversions || {});
    console.log(`Asset processed: ${id}, formats: ${formats}`);
    // Update database with URLs and formats
  } else if (status === "ERROR") {
    console.error(`Processing failed: ${id}`, assetData.errors);
    // Log error, alert ops
  }
}

function handleDeletionEvent(payload) {
  const { id, event, keys, status } = payload;

  if (event === "file-deleted") {
    console.log(`Asset deleted: ${id}, keys: ${keys}`);
    // Soft delete from your system
  } else if (event === "file-undeleted") {
    console.log(`Asset restored: ${id}`);
    // Restore in your system
  }
}

app.listen(5000);