API and integrations Reference Media library

Media library

A channel's media library: the uploaded images and the editorial metadata around them. Files are uploaded as multipart/form-data and addressed by their id — unlike the rest of this API, because a file has no other stable, unique name; two uploads may legitimately be called hero.jpg. The url in the response is what goes into a page section or an article's featuredImageUrl; the file itself is served by the CDN and needs no API key.

5 calls GET POST PATCH DELETE Base URL https://api.fluit.cloud/preview

Authentication, error codes, rate limits, idempotency and pagination apply to every call and are documented once under Getting started.

GET /channels/{channelCode}/media

List a channel's media library

Returns the images uploaded to the channel, newest first. Each entry carries the url the file is served on — that is what goes into a page section or an article's featured image — and the id used to address the record on this API.

Show the full description

Delta sync: ?modifiedSince= (ISO 8601 UTC datetime) returns records created or changed at or after that instant, and is the intended way to run an incremental sync. A change anywhere inside the record counts: editing a line moves the parent's modifiedDate too, so no change can hide below the resource level. Deletions are not visible here: a deleted record is really gone, so it simply stops appearing, which is indistinguishable from "unchanged". Poll GET /preview/deletions?deletedSince= alongside this endpoint to learn what was removed.

media:read Paginated Supports ?modifiedSince

Path parameters

Field	Type	Description
`channelCode` Required	string	Code of the channel whose media library to list.

Query parameters

Field	Type	Description
`folder`	enum	Restricts to one folder: Hero, Banner, Sections or Content. `HeroBannerSectionsContentDocuments`
`search`	string	Matches file name, title and alt text, case-insensitively and on partial words.
`modifiedSince`	string(date-time)	Returns only records created or changed at or after this instant (ISO 8601 UTC datetime). A change anywhere inside the record counts, including on its lines.
`page`	integer	Page to return, 1-based. Default 1.
`pageSize`	integer	Number of records per page. Default 50, max 200.

Responses

200


                      PagedResult_PublicMediaAssetResponse

Paginated response: the fields below sit in items[], wrapped in totalCount, page, pageSize, totalPages, hasPreviousPage and hasNextPage. Paginated

Field	Type	Description
`altText`	string · nullable	Alt text for accessibility, or null if the editor has not written one.
`caption`	string · nullable	Caption, or null.
`channelCode` Required	string · nullable	The channel the file belongs to.
`contentType` Required	string · nullable	MIME type, e.g. `image/webp`.
`createdDate` Required	string(date-time)	When the file was uploaded (UTC).
`fileName` Required	string · nullable	The original file name it was uploaded under.
`fileSize` Required	integer	File size in bytes.
`folder` Required	enum	Where in the storefront a media file belongs. Filters the library, and decides the folder a <em>new</em> upload is stored under. `HeroBannerSectionsContentDocuments`
`height`	integer · nullable	Image height in pixels, or null when the dimensions were not read.
`id` Required	string(uuid)	The file's identifier in the library. Its address on this API.
`links`	Links	Hypermedia links for a public API resource. Exposed as a computed `links` property on the public response DTOs so that create and read responses carry the same self-reference — the canonical URL is derived from the business key already present on the DTO and can never drift from the route it points at.
`modifiedDate`	string(date-time) · nullable	When its metadata was last changed (UTC), or null if never changed.
`title`	string · nullable	Display name in the library, or null to fall back to the file name.
`url` Required	string · nullable	The public URL the file is served on. This is what a page section references.
`width`	integer · nullable	Image width in pixels, or null when the dimensions were not read.

400


                      ProblemDetails

folder got a value outside its list.

Field	Type
`detail`	string · nullable
`instance`	string · nullable
`status`	integer · nullable
`title`	string · nullable
`type`	string · nullable

404


                      ProblemDetails

No channel with that code.

Field	Type
`detail`	string · nullable
`instance`	string · nullable
`status`	integer · nullable
`title`	string · nullable
`type`	string · nullable

Standard errors: 401403 Errors

Examples

curl

curl "https://api.fluit.cloud/preview/channels/{channelCode}/media"

Response 200

{
  "hasNextPage": true,
  "hasPreviousPage": true,
  "items": [
    {
      "altText": "string",
      "caption": "string",
      "channelCode": "STD",
      "contentType": "image/jpeg",
      "createdDate": "2026-06-11T09:24:13.418",
      "fileName": "widget-a-front.jpg",
      "fileSize": 42,
      "folder": "Hero",
      "height": 42,
      "id": "0f8b2c1e-4d3a-4b7e-9f10-2a6c5d8e1b44",
      "links": {
        "self": "string"
      },
      "modifiedDate": "2026-06-11T09:24:13.418",
      "title": "string",
      "url": "https://cdn.fluit.cloud/assets/widget-a-front.jpg",
      "width": 42
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 137,
  "totalPages": 3
}

Base URL https://api.fluit.cloud/preview. The response example is generated from the schema: the shape is right, the values are made up.

POST /channels/{channelCode}/media

Upload a file to the media library

Uploads a file as multipart/form-data. The field name is 'file'; everything else is a query parameter. Supported types: PNG, JPEG, GIF, WebP and SVG (max 10 MB), MP4 and WebM (max 50 MB), and PDF (max 20 MB).

Show the full description

The size limit is per type: a 10 MB image is nearly always the camera original by mistake, while a 40 MB product video is ordinary. folder decides which part of the storefront the file is filed under and defaults to Content; it only affects filing and filtering, not what the file can be used for. The response is the same representation as GET on the file: its url goes into a page section or an article's featuredImageUrl, its id addresses the record here. The file itself is served by the CDN and needs no API key. This POST takes no Idempotency-Key — a multipart body cannot be hashed the way a JSON one can — so a retry after a network failure may create a second copy; list the folder and compare, or delete the duplicate. Known error codes: ChannelMediaAsset.EmptyFile, ChannelMediaAsset.FileTooLarge, ChannelMediaAsset.UnsupportedType. **Not idempotent.** A file upload carries no Idempotency-Key: the body cannot be buffered and hashed the way a JSON request can. Retrying after a network failure may therefore create a second copy — list the folder and compare before retrying, or delete the duplicate afterwards.

media:write

Path parameters

Field	Type	Description
`channelCode` Required	string	Code of the channel to upload into.

Query parameters

Field	Type	Description
`folder`	string	Where the file belongs: Hero, Banner, Sections or Content. Defaults to Content.
`title`	string	Display name in the library. Defaults to the file name.
`altText`	string	Alt text for accessibility. Strongly recommended.
`caption`	string	Caption shown under the image.

Body

Field	Type
`file` Required	string(binary)

Responses

201


                      PublicMediaAssetResponse

Location — URL of the newly created resource.

Field	Type	Description
`altText`	string · nullable	Alt text for accessibility, or null if the editor has not written one.
`caption`	string · nullable	Caption, or null.
`channelCode` Required	string · nullable	The channel the file belongs to.
`contentType` Required	string · nullable	MIME type, e.g. `image/webp`.
`createdDate` Required	string(date-time)	When the file was uploaded (UTC).
`fileName` Required	string · nullable	The original file name it was uploaded under.
`fileSize` Required	integer	File size in bytes.
`folder` Required	enum	Where in the storefront a media file belongs. Filters the library, and decides the folder a <em>new</em> upload is stored under. `HeroBannerSectionsContentDocuments`
`height`	integer · nullable	Image height in pixels, or null when the dimensions were not read.
`id` Required	string(uuid)	The file's identifier in the library. Its address on this API.
`links`	Links	Hypermedia links for a public API resource. Exposed as a computed `links` property on the public response DTOs so that create and read responses carry the same self-reference — the canonical URL is derived from the business key already present on the DTO and can never drift from the route it points at.
`modifiedDate`	string(date-time) · nullable	When its metadata was last changed (UTC), or null if never changed.
`title`	string · nullable	Display name in the library, or null to fall back to the file name.
`url` Required	string · nullable	The public URL the file is served on. This is what a page section references.
`width`	integer · nullable	Image width in pixels, or null when the dimensions were not read.

400


                      ProblemDetails

The file is empty, larger than the limit for its type, not one of the supported types, has no file name, folder got a value outside its list, or title, altText or caption is longer than allowed.

Field	Type
`detail`	string · nullable
`instance`	string · nullable
`status`	integer · nullable
`title`	string · nullable
`type`	string · nullable

404


                      ProblemDetails

No channel with that code.

Field	Type
`detail`	string · nullable
`instance`	string · nullable
`status`	integer · nullable
`title`	string · nullable
`type`	string · nullable

Standard errors: 401403 Errors

Examples

curl

curl -X POST "https://api.fluit.cloud/preview/channels/{channelCode}/media" \
  -H "Content-Type: application/json" \
  -d @body.json

Response 201

{
  "altText": "string",
  "caption": "string",
  "channelCode": "STD",
  "contentType": "image/jpeg",
  "createdDate": "2026-06-11T09:24:13.418",
  "fileName": "widget-a-front.jpg",
  "fileSize": 42,
  "folder": "Hero",
  "height": 42,
  "id": "0f8b2c1e-4d3a-4b7e-9f10-2a6c5d8e1b44",
  "links": {
    "self": "string"
  },
  "modifiedDate": "2026-06-11T09:24:13.418",
  "title": "string",
  "url": "https://cdn.fluit.cloud/assets/widget-a-front.jpg",
  "width": 42
}

Base URL https://api.fluit.cloud/preview. The response example is generated from the schema: the shape is right, the values are made up.

GET /channels/{channelCode}/media/{assetId}

Read one media file

Returns the library record for one file: the url it is served on plus its editorial metadata. This endpoint returns JSON, not the file itself — the bytes are fetched from url, which is served by the CDN and needs no API key. Responses carry a weak ETag; pass it back in If-None-Match to get 304 Not Modified while the record is unchanged.

media:read Supports ETag

Path parameters

Field	Type	Description
`channelCode` Required	string	Code of the channel the file belongs to.
`assetId` Required	string(uuid)	The file's id, as returned by the upload and by the listing.

Responses

200


                      PublicMediaAssetResponse

ETag — Weak validator for this representation. Pass it back in If-None-Match to get 304 Not Modified while the record is unchanged.

Field	Type	Description
`altText`	string · nullable	Alt text for accessibility, or null if the editor has not written one.
`caption`	string · nullable	Caption, or null.
`channelCode` Required	string · nullable	The channel the file belongs to.
`contentType` Required	string · nullable	MIME type, e.g. `image/webp`.
`createdDate` Required	string(date-time)	When the file was uploaded (UTC).
`fileName` Required	string · nullable	The original file name it was uploaded under.
`fileSize` Required	integer	File size in bytes.
`folder` Required	enum	Where in the storefront a media file belongs. Filters the library, and decides the folder a <em>new</em> upload is stored under. `HeroBannerSectionsContentDocuments`
`height`	integer · nullable	Image height in pixels, or null when the dimensions were not read.
`id` Required	string(uuid)	The file's identifier in the library. Its address on this API.
`links`	Links	Hypermedia links for a public API resource. Exposed as a computed `links` property on the public response DTOs so that create and read responses carry the same self-reference — the canonical URL is derived from the business key already present on the DTO and can never drift from the route it points at.
`modifiedDate`	string(date-time) · nullable	When its metadata was last changed (UTC), or null if never changed.
`title`	string · nullable	Display name in the library, or null to fall back to the file name.
`url` Required	string · nullable	The public URL the file is served on. This is what a page section references.
`width`	integer · nullable	Image width in pixels, or null when the dimensions were not read.

304 Empty body.

ETag — Weak validator for this representation. Pass it back in If-None-Match to get 304 Not Modified while the record is unchanged.

404


                      ProblemDetails

No channel with that code, or no file with that id in the channel.

Field	Type
`detail`	string · nullable
`instance`	string · nullable
`status`	integer · nullable
`title`	string · nullable
`type`	string · nullable

Standard errors: 401403 Errors

Examples

curl

curl "https://api.fluit.cloud/preview/channels/{channelCode}/media/{assetId}"

Response 200

{
  "altText": "string",
  "caption": "string",
  "channelCode": "STD",
  "contentType": "image/jpeg",
  "createdDate": "2026-06-11T09:24:13.418",
  "fileName": "widget-a-front.jpg",
  "fileSize": 42,
  "folder": "Hero",
  "height": 42,
  "id": "0f8b2c1e-4d3a-4b7e-9f10-2a6c5d8e1b44",
  "links": {
    "self": "string"
  },
  "modifiedDate": "2026-06-11T09:24:13.418",
  "title": "string",
  "url": "https://cdn.fluit.cloud/assets/widget-a-front.jpg",
  "width": 42
}

Base URL https://api.fluit.cloud/preview. The response example is generated from the schema: the shape is right, the values are made up.

PATCH /channels/{channelCode}/media/{assetId}

Update a media file's metadata

Partially updates one file's editorial metadata. Only provided fields are updated (JSON Merge Patch semantics). Omitted fields are left unchanged. Pass null to clear title, altText or caption; folder cannot be null.

Show the full description

Unknown fields are rejected with 400, naming the field and listing the ones this endpoint accepts. The file itself cannot be replaced here — uploading a new file gives it a new url, so replacing one is an upload plus updating whatever referenced the old. Changing folder re-files the asset in the library but does not move the stored file: the url is unchanged, so links already pointing at it keep working. The folder a file was uploaded into therefore stays visible in its url.

media:write

Path parameters

Field	Type	Description
`channelCode` Required	string	Code of the channel the file belongs to.
`assetId` Required	string(uuid)	The file's id.

Body required

Field	Type	Description
`altText`	string · nullable	Alt text for accessibility. Pass `null` to clear.
`caption`	string · nullable	Caption. Pass `null` to clear.
`folder`	enum	Where in the storefront a media file belongs. Filters the library, and decides the folder a <em>new</em> upload is stored under. `HeroBannerSectionsContentDocuments`
`title`	string · nullable	Display name in the library. Pass `null` to fall back to the file name.

Responses

204 Empty body.

400


                      ProblemDetails

The body is not a JSON object, contains a field this endpoint does not have, a field present in it failed validation, or folder was sent as null or with a value outside its list.

Field	Type
`detail`	string · nullable
`instance`	string · nullable
`status`	integer · nullable
`title`	string · nullable
`type`	string · nullable

404


                      ProblemDetails

No channel with that code, or no file with that id in the channel.

Field	Type
`detail`	string · nullable
`instance`	string · nullable
`status`	integer · nullable
`title`	string · nullable
`type`	string · nullable

Standard errors: 401403 Errors

Examples

curl

curl -X PATCH "https://api.fluit.cloud/preview/channels/{channelCode}/media/{assetId}" \
  -H "Content-Type: application/json" \
  -d @body.json

Response 400

{
  "detail": "string",
  "instance": "string",
  "status": 42,
  "title": "string",
  "type": "string"
}

Base URL https://api.fluit.cloud/preview. The response example is generated from the schema: the shape is right, the values are made up.

DELETE /channels/{channelCode}/media/{assetId}

Delete a media file

Removes the library record and the stored file. Nothing checks whether a page still references the url — a section pointing at a deleted file keeps its broken link, so look the file up in the pages that use it first.

Show the full description

The deletion leaves a tombstone under GET /preview/deletions with resource 'media', so a client syncing with ?modifiedSince= sees it disappear.

media:write

Path parameters

Field	Type	Description
`channelCode` Required	string	Code of the channel the file belongs to.
`assetId` Required	string(uuid)	The file's id.

Responses

204 Empty body.

404


                      ProblemDetails

No channel with that code, or no file with that id in the channel.

Field	Type
`detail`	string · nullable
`instance`	string · nullable
`status`	integer · nullable
`title`	string · nullable
`type`	string · nullable

Standard errors: 401403 Errors

Examples

curl

curl -X DELETE "https://api.fluit.cloud/preview/channels/{channelCode}/media/{assetId}"

Response 404

{
  "detail": "string",
  "instance": "string",
  "status": 42,
  "title": "string",
  "type": "string"
}

Base URL https://api.fluit.cloud/preview. The response example is generated from the schema: the shape is right, the values are made up.

Schemas

The objects this group's calls refer to. The field tables above go one level deep and link here rather than repeating the same schema on every endpoint.

Links


                      PublicLinks

Hypermedia links for a public API resource. Exposed as a computed `links` property on the public response DTOs so that create and read responses carry the same self-reference — the canonical URL is derived from the business key already present on the DTO and can never drift from the route it points at.

Field	Type	Description
`self`	string · nullable	Canonical URL of the resource, relative to the API base address.