Batches

Note

Creating a batch is currently only possible through the API. However, existing batches can be viewed through the Dashboard.

The Batch and Task APIs allows the generation of large quantities of Thngs quickly and easily. Creating large collections of Thngs works in the following manner:

1. The Batch API is used to create a placeholder for a specific batch resource and associated metadata (the data that all Thngs in batch share), but not the Thngs themselves. This represents some production batch or group of physical products to be manufactured, each of which will have a Thng generated using a Task on this batch resource.

2. Once you have created a batch object, you can populate it with Thngs using the Task API, where you can choose the parameters for the generation task such as the quantity of Thngs to generate, the product ID, common identifiers/custom fields, list of unique IDs, and so on.

This page describes operations on the metadata of batches. For operations you can do on a batch refer to the Tasks API page.

API Status General Availability: /batches /batches/:batchId

BatchDocument Data Model

See also: ScopesDocument

Filterable Fields

This resource type can be filtered using the following fields and operators.

Create a Batch

Batches are created by sending a POST request containing a JSON document to the /batches resource.

The Location header in the response returns the URL of the Batch resource that was created, which is always in the format /batches/:batchId, where batchId is the unique identifier of this batch assigned by the Platform.

Read All Batches

To retrieve the list of all batches in your account or project, simply do a GET on the /batches resource. The result may be paginated if there are more than 30 items. You can also use ?filter or ?ids query params to restrict the returned resources.

To retrieve a subset of all the batches you have created, simply use a filter. Filterable fields are: name, tags, identifiers, createdAt, and products.

Read a Batch

You can retrieve a batch document with a GET on the batch URL containing the batchId.

Update a Batch

You can update the data of a batch using any subset of a valid BatchDocument model.

Delete a Batch

To delete a batch, simply send a DELETE request to the batch's URL.

Running Tasks on a Batch

On its own, a batch describes metadata about a group of Thngs it will contain. To learn how to populate the batch with Thngs, see Tasks.