Start Desk Batch
POST /desk/batch/start
Freeze a ranked slice of the queue into today’s batch.
This is what makes the day finite. Cards added to the queue afterwards do
NOT join the batch on their own - use /batch/pull to take more.
Authorizations
Parameters
Header Parameters
Request Body required
Freeze today’s ranked queue into a finite batch.
item_ids is typed list[UUID], not list[str], so a malformed id is a
request-validation 422 that NAMES the offending element. Typed as strings,
the app’s own list[UUID] model raises a pydantic ValidationError from
inside the handler body instead - the same class of bare-500 the path
guard exists to prevent, one layer in.
object
Decision ids to freeze into the batch. 1-80 - the cap is the app’s.
The rep’s UTC offset in MINUTES (local = UTC + tz_offset). A batch is scoped to the rep’s local day, so a wrong offset returns yesterday’s batch or starts a second one.
Responses
201
Successful Response
object
Today’s frozen batch.
A batch is FINITE by design: the rep freezes a ranked slice of the queue so
the day has an end. None from the app means no batch has been started
today, which is different from a batch with no items left - the response
keeps that distinction rather than flattening both to an empty batch.
object
422
Validation Error