Custom Headers

While the platform will set appropriate CORS headers for IIIF API interactions, you might with to add in your own headers. This is especially true if you have a proxy server in front of the platform - you might want to specify cache control headers.

{
    "@context": "https://dlcs.github.io/vocab/context/future.json",
    "@id": "https://api.dlcs.io/customers/2/customHeaders/ffd2682d-85db-45da-9a25-9b495a549e20",
    "@type": "vocab:CustomHeader",
    "space": 7,
    "role": "https://api.dlcs.io/customers/2/roles/clickthrough",
    "key": "Cache-Control",
    "value": "private, max-age=600"
}

/customers/{customer}/customHeaders/{identifier}

As the platform must assign the ../{identifier} part, you can only create a new custom header with a POST to the customer's customHeaders collection.

key

The HTTP Header name, e.g., "My-Header". This field is required.

value

The HTTP Header value, e.g., "my header value". This field is required.

space

If provided, the header will only be set on responses for assets in that space.

role

If provided, the header will only be set on responses for assets that have this role.

This field is a single value, not a comma-delimited list (so you need multiple custom headers for multiple roles).

Multiple headers with same key

The platform will only assign one header for a give key on a response, but it's possible to have multiple custom headers with the same key. They are evaluated in this order, with later matches overriding earlier ones:

1. Custom header has no space or role
2. Custom header matches the asset space but has no role
3. Custom header has no space but matches an asset role
4. Custom header has matching space and role

touched 2025-09-23T12:04:54