Queues

While you can register assets individually (and update them individually), many workflow or systems integration scenarios require processing of large number of assets. This kind of work is better suited to a queue: give the platform work to do, and let it do that work asynchronously (e.g., register 1000 assets for a large book).

You can post a Collection of assets to the Queue for processing. This results in the creation of a Batch resource. You can then retrieve these batches to monitor the progress of your images.

The queue is for registration of new assets, and reprocessing of existing assets. You can update assets synchronously individually or by the PATCH operation on space.images.

{
    "@context": "https://dlcs.github.io/vocab/context/future.json",
    "@id": "https://api.dlcs.io/customers/2/queue",
    "@type": "vocab:CustomerQueue",
    "size": 170,
    "batchesWaiting": 0,
    "imagesWaiting": 0,
    "batches": "https://api.dlcs.io/customers/2/queue/batches",
    "images": "https://api.dlcs.io/customers/2/queue/images",
    "active": "https://api.dlcs.io/customers/2/queue/active",
    "recent": "https://api.dlcs.io/customers/2/queue/recent",
    "priority": "https://api.dlcs.io/customers/2/queue/priority"
}

/customers/{customer}/queue

size

Number of total assets in your queue, across all batches. This number decreases as the platform processes your assets.

batchesWaiting

??

imagesWaiting

??

batches

A link to a paged Collection of Batches. Batches represent the separate jobs you have submitted to the queue.

The returned collection allows you to page through all available batches, but presents the most recent first. This collection does not shrink as the platform processes jobs, but may reduce over time as very old batches are archived. This collection contains batches that have finished processing, batches that are currently processing (active), and batches that are yet to be processed.

/customers/{customer}/queue/batches

images

A link to a paged Collection of assets, giving a merged view of assets on the queue, across batches. Typically you’d use this to look at the top or bottom of the queue (first or large page). This collection grows as you submit jobs to the queue, and shrinks as the platform processes them.

/customers/{customer}/queue/images

active

A link to a paged Collection of Batches that are currently in process - that contain at least one asset still being worked on. When you submit a batch it won't be active immediately (there may be other jobs ahead of it). It becomes active as the platform processes it (is present in this collection), and then drops out of this collection once finished. It drops out regardless of the success of the batch.

/customers/{customer}/queue/active

recent

A link to a paged Collection of Batches that have finished, and are not marked as superseded.

/customers/{customer}/queue/recent

priority

This endpoint acts in the same way as /customers/{customer}/queue, but any batches posted here will "jump the queue" and be processed ahead of the main queue. It defeats the purpose of this endpoint of you always post all of your jobs to it instead of the main queue. The priority endpoint is useful for:

• processing something quickly when there are a large number of non-critical items in the main queue.
• processing jobs initiated by a user interface, where a quicker response time is better for the user experience.

/customers/{customer}/queue/priority

Note that GET is not supported. Batches sent to the priority queue will be visible in the batch collections available on the main queue: batches, active and recent. The only difference is that they will be picked up and processed sooner went sent to the priority queue - so a batch may appear sooner in recent.

The priority queue cannot be used for assets that specify the iiif-av delivery channel.

Manifest Queues 🆕

As well as a Customer queue, any Manifest you create has its own queue available; assets sent to that queue are processed in the same way as described above, but they are also associated with the Manifest.

See IIIF Manifests and Collections.

The Global Queue

The platform also has a queue link from the entry point.

{
    "@context": "https://dlcs.github.io/vocab/context/future.json",
    "@id": "https://api.dlcs.io/queue",
    "@type": "vocab:Queue",
    "incoming": 0,
    "success": 0,
    "failed": 0,
    "priority": 0
}

/queue

All of the properties of the vocab:Queue resource are integer counts.

incoming

Number of assets currently on the main queues of all customers on the platform.

This gives an indication of how busy the platform is at any time. While the platform will automatically scale to process larger queues, you still might want to base some activity decisions on this value.

success

Always 0.

failed

Always 0.

priority

Number of assets currently on the priority queues of all customers on the platform.

Priority queues are processed in preference to main queues (with certain conditions).

Number of assets currently on the queue.

touched 2025-09-23T12:04:54