File Links
File links give you a revocable public URL for a stored file. Use them for product images or product videos that you want to embed in customer-facing surfaces.
The public open URL should be shown only to the people or systems that should have access.
The file link object
A file link stores the sharing policy for one file. The public URL is returned when you create the link, then managed by you as a secret.
Properties
Create a file link
Create a revocable public URL for a linkable file. Only product_image and product_video files can be exposed through file links; use Download file contents for private assets such as support documents and product downloads.
Each successful create returns a new link and bearer URL. Creation is intentionally not idempotent: do not attach an Idempotency-Key or automatically repeat the request after an uncertain response. Store the first successful url and file_link.id; use the ID to look up or revoke the link later.
Request body
Defaults and validation
expires_atmust be in the future and defaults to 24 hours after creation.- Delivery mode defaults to
download. Disposition defaults toinlinefor inline mode andattachmentotherwise. If mode and disposition are both omitted, downloads are enabled by default. attachmentdisposition requiresaccess.allow_download: true.max_accessesmust be nonnegative;0means unlimited successful opens.content_typemust use valid MIME syntax, andfilenamecannot contain HTTP control characters.- Every allowed origin must contain only a scheme and host, with no credentials, query, fragment, or non-root path. Every allowed IP range must be valid CIDR notation.
Response
The response returns a top-level file_link object and a top-level url. Lookup responses do not expose token material later.
Request
curl https://api.zebo.dev/file_links/create \
-H "Authorization: Bearer $COMMERCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_id": "file_4q6YcQk1RzPv2mDa8nFw0sHu",
"delivery": { "mode": "inline" },
"access": { "allow_download": true, "max_accesses": 100 },
"expires_at": "2026-07-06T12:30:00Z"
}'
{
"file_link": {
"id": "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
"kind": "public",
"file_id": "file_4q6YcQk1RzPv2mDa8nFw0sHu",
"purpose": "product_image",
"status": "active",
"active": true,
"delivery": {
"mode": "inline",
"filename": "hero.png",
"content_type": "image/png",
"disposition": "inline"
},
"access": { "allow_download": true, "max_accesses": 100, "access_count": 0 },
"created_by": { "type": "api_key" },
"created_at": "2026-06-05T12:30:00Z",
"updated_at": "2026-06-05T12:30:00Z",
"expires_at": "2026-07-06T12:30:00Z"
},
"url": "<FILE_LINK_URL>"
}
Lookup a file link
Retrieve file-link details by ID. Lookup never returns the original bearer token or public URL.
Request body
Response
The response returns a top-level file_link object.
Request
curl https://api.zebo.dev/file_links/lookup \
-H "Authorization: Bearer $COMMERCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"flink_8pQz3LkY6mN2vT9sB4cD1eF0"}'
Page file links
List file links for the authorized application. Use filters to find links for one file or to audit active, revoked, expired, and disabled links.
Request body
Response
Links are returned newest first. The response returns a top-level page object with file_links, number, and size; size is the number of links returned, not the requested limit. An exhausted page returns file_links: [] and size: 0. Page numbers and sizes below 1 are normalized to their defaults.
Request
curl https://api.zebo.dev/file_links/page \
-H "Authorization: Bearer $COMMERCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"file_id":"file_4q6YcQk1RzPv2mDa8nFw0sHu","status":"active","page_number":1,"page_size":25}'
Revoke a file link
Revoke a link so its public URL can no longer serve the file. Revocation is the preferred response when a URL was shared with the wrong recipient or the file no longer belongs in a customer-facing surface.
Request body
Response
The response returns the updated file_link object with status set to revoked.
Request
curl https://api.zebo.dev/file_links/revoke \
-H "Authorization: Bearer $COMMERCE_API_KEY" \
-H "Idempotency-Key: revoke-file-link-001" \
-H "Content-Type: application/json" \
-d '{
"id": "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
"revoked_by": { "type": "user", "id": "usr_support_123" }
}'
Open a file link
Open is the public endpoint behind a file-link URL. It does not use API-key authentication; the id and token query parameters in the URL are the bearer capability.
Query parameters
Response
Use the complete URL returned by Create a file link unchanged. The API validates the token, active state, expiry, origin, client address, and access limit before delivery.
Stream or inline delivery returns 200 OK with the file bytes. Redirect delivery returns 302 Found with a short-lived download URL in the Location header. A successful open increments access.access_count only after the file stream or redirect is ready; delivery failures do not consume the access limit.
Access-policy failures return 403; an unknown link or invalid token returns 404; an inactive, expired, or exhausted link returns 410. Unreadable contents return 424, an unsupported stored representation returns 422, and a temporarily unavailable operation returns 503.
Request
curl "<FILE_LINK_URL>" \
--output hero.png