How Vyso DAM fits into an application stack

Vyso connects to an application through two public surfaces: an authenticated Developer API for managing the media library, and CDN URLs for serving image representations. An editor can select an asset through the API, save its reference in a CMS record, and let the website render it through the CDN.

Keep those responsibilities separate. Library operations belong in the management path. A browser that already has the asset key and presentation rule can request the image directly from the delivery path.

Two surfaces, two jobs

The Developer API uses https://api.vyso.io/v1. It provides authenticated operations for uploads, asset retrieval and updates, metadata, collections, search, delivery presets and workspace settings. Management resources are scoped to the authenticated workspace.

Image delivery uses https://cdn.vyso.io. A public URL identifies the source asset and the transformation chain or preset to apply. The response is an image representation for the consuming application.

Management path
Authorized editor / CMS / backend
    → Developer API
    → Vyso media library

Delivery path
Application content record
    → frontend emits CDN image URL
    → browser requests CDN
    → image representation

The management API is the control plane: it changes or inspects library state. The CDN is the delivery plane: it serves the requested image. Preset configuration crosses this boundary deliberately. You manage the recipe through the API and request its output through the CDN.

Put authentication in the management path

Protected management requests use Authorization: Bearer <clerk-session-token>, as described in the authentication reference. Clerk handles sign-in and token issuance. Obtain a token from the supported Clerk session flow; a session token is not a permanent API key.

A trusted backend can make management requests on behalf of an authorized session. An authenticated editor interface can also make requests in its authorized application context. Keep privileged credentials out of public frontend code, and refresh session tokens through the supported authentication flow.

Your application still decides who can change its CMS records or publish a page. Access to a Vyso workspace does not define the authorization rules for your own application.

Public CDN image requests do not use the management bearer token. A protected library operation therefore does not make its delivery URL private. Use the public delivery model for images intended to be publicly accessible.

Connect a CMS record to an asset

Consider a marketing page with a hero image. The CMS stores the page content; Vyso stores the source asset and supplies its delivery representation.

1. An authorized editor searches the library or uploads a source image through the Developer API.
2. The application reads the selected asset's identifier and source key from the API response.
3. The CMS saves that reference with the page, along with its presentation rule and placement-specific alternative text.
4. When rendering the page, the frontend reads the saved reference and emits the corresponding CDN URL.
5. The browser requests the image from the CDN.

Library search helps the editor choose an asset. A visitor loading that page does not need to repeat the search or retrieve the asset through the management API for every image render.

CMS publication remains a CMS operation. Saving metadata in Vyso does not publish the page or write its asset reference into the CMS. The detailed guide to building workflows with the Vyso API covers the upload, metadata and collection requests behind this management flow.

Store asset identity separately from presentation

Asset responses contain an id for management requests and a key for source lookup in delivery URLs. A successful new upload returns these within its asset object; retrieving an asset also returns an asset object. Use the values actually returned by the API.

The assets reference uses the identifier in routes such as GET /v1/assets/:assetId. Delivery uses the returned key, including its source extension. A display filename or user title is descriptive information. Do not derive the delivery key from either one.

Where the content model allows it, keep the asset reference separate from the presentation rule. The same source can be used with a hero preset on one page and a smaller card recipe elsewhere. Changing the card dimensions then does not require changing which asset the content record identifies.

Storing a complete delivery URL can also be appropriate for a fixed output. The trade-off is that asset identity and presentation settings are bundled together. Keep separate values when templates need to choose or change the presentation.

Collections can help editors organize project or campaign material. The application still owns relationships such as which image belongs to a page, its position in a gallery, and the text used beside it.

A delivery URL selects the representation

Vyso's current delivery syntax puts transformations in path segments. Slashes separate operations; parameters follow a colon. This example requests a width-1200 representation, explicitly selects WebP, then applies a quality setting:

https://cdn.vyso.io/resize:width=1200/format:type=webp/quality:value=80/ASSET_ID.jpg

ASSET_ID.jpg stands for the actual source key returned by your library. The source extension remains in the URL even when the requested output is WebP. The response Content-Type identifies the delivered format.

The chain runs in URL order. A width-only resize preserves aspect ratio, and enlargement is disabled by default. Quality 80 is an example setting to inspect in the intended placement, not a universal recommendation.

The original remains the source for other representations. The transformation reference documents supported operations and parameters. Output format is an explicit choice in this example; the URL does not ask Vyso to select a format by detecting the browser.

Once the application knows the key and recipe, it can emit this URL directly. Routing each image through an application backend that calls the management API and proxies the image bytes adds another request path that this public delivery flow does not require.

Use presets for repeated placements

A preset stores a reusable transformation configuration. Create or update it through the authenticated presets API, then use its slug in the delivery URL:

https://cdn.vyso.io/preset/hero-1200/ASSET_ID.jpg

hero-1200 is an illustrative slug for a preset you create, not a built-in configuration. Delivery resolves the preset within the source asset's workspace. An unrelated workspace's preset is not a substitute.

Presets move repeated transformation rules out of scattered templates. Direct chains suit a placement with deliberately different parameters. Decide which recipes applications should share, and who reviews a configuration change before those applications rely on it.

Keep rendering decisions in the application

The basic integration uses HTTP requests and image URLs. A React component can use a CDN URL in image markup. A server-rendered application can emit the same URL into HTML. A CMS can store the reference and render it later. These basic operations do not require a framework-specific SDK.

The frontend supplies layout, srcset, sizes, alternative text and loading priority. It can expose several transformed widths as responsive candidates, but it must describe those candidates and the rendered slot correctly.

An image URL alone does not determine page performance. The application chooses dimensions, discovery timing and loading behavior. Use the separate image quality and performance workflow when making those choices.

Handle failed management requests explicitly

Inspect both the HTTP status and JSON response body. The error reference includes responses such as {"error":"Asset not found."}. Preserve useful error details instead of treating every unsuccessful response as a network retry.

A 400 calls for correcting the request. A 401 calls for a valid session through the authentication flow. For 404, check the resource identifier and its availability to the authenticated workspace. A 409 can indicate a conflicting collection or preset name that the application needs to resolve.

Rate-limited requests return 429 with Retry-After in seconds. Wait for that interval before another eligible request. Limits are configurable; consult the current rate-limit documentation instead of embedding an assumed permanent quota in the architecture.

For transient 5xx responses, use bounded retries with backoff for safe reads. A lost upload or write response does not prove that the operation failed. Reconcile what was stored before repeating an operation that could create a duplicate or overwrite a newer change.

Save the chosen asset reference so rendering does not repeatedly rediscover it. Refresh library data when the editor needs it or through a deliberate synchronization process. Avoid tight polling loops.

Treat library changes and delivery changes separately

A stable delivery URL identifies a requested representation and allows generated output to be reused. Inspect Cache-Control and related headers when debugging. The caching guidance explains this behavior without promising a deployment-independent lifetime.

Different changes need different handling:

• A metadata change updates library information. Text copied into a CMS record needs its own update if the application should reflect it.
• A source-image change affects the input used to generate representations. If a URL stays the same, account for caches and verify the image consumers receive.
• A preset change alters a shared recipe. Check consuming placements and cache behavior before relying on the revised output.
• A transformation-path change requests a different representation. Consumers receive that URL only when the application emits or publishes it.

A new preset slug can make a changed recipe explicit during a rollout. A new asset key gives a replacement source its own reference. These choices help the application control which version it publishes; they do not replace downstream copies or guarantee immediate cache invalidation.

Check one complete page before expanding the integration

• Can an authorized editor select an asset and save its returned ID and key?
• Does the page render its chosen CDN representation without a management request for each image?
• Are preset configuration, responsive markup and placement-specific text owned by the appropriate parts of the application?
• Do failed requests preserve enough information to resolve authentication, validation and rate-limit problems?
• Have you tested how source and preset changes reach the published page after caching is considered?