Update Collection (Pause / Resume)

Pause or resume a collection. This PATCH is state-transition only — it does not update arbitrary fields such as priority, assignment, or business context.

PATCH /api/collections/{id}

Authorization

• Analyst / Admin: Required (must have an analyst profile). Customers receive 403.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID

Request Body

Field	Type	Required	Description
status	string	Yes	Must be paused or in_progress (resume)

Request Example

{
  "status": "paused"
}

Response

{
  "success": true,
  "status": "paused"
}

On resume (in_progress), the collection is re-queued and the response reports the queued state:

{
  "success": true,
  "status": "queued"
}

Side Effects

• A chain-of-custody event is logged for the transition.
• Resuming sets status to queued and enqueues an execute-collection job for the worker.

Example: Resume Collection

curl -X PATCH "https://api.traces.io/api/collections/col_abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "in_progress" }'

Error Responses

400 Bad Request

Invalid status value or illegal transition:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Status must be 'paused' or 'in_progress'"
  }
}

403 Forbidden

Non-analyst attempting to update:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Analyst access required"
  }
}