API reference · Review queue

Review queue

Everything a workflow parked for a human, and the endpoints to decide it. The rules behind approval are on Gates and review.

GET/v1/queueRuns waiting on a decision.
GET/v1/queue/countJust the number.
POST/v1/queue/{run_id}/decisionDecide one run.
POST/v1/queue/decisionsDecide many.

GET /v1/queue

Runs in review, each with the gate that held it and its QA record.

requestbash
curl -s "https://api.esy.com/v1/queue?workspaceId=$WS&limit=20" \
  -H "Authorization: Bearer $ESY_API_KEY"
one itemjson
{
  "runId": "run-62af77b1",
  "templateId": "generate-clip-art-asset-v2",
  "gateId": "gate-review",
  "gateName": "Review",
  "status": "review",
  "artifactId": "artifact-a5db7c7d",
  "artifactTitle": "Flat Clip Art Asset",
  "artifactStatus": "review",
  "qa": {
    "status": "pending_review",
    "checks": [
      { "id": "text-gate", "label": "Text gate", "status": "pass", "detail": "" },
      { "id": "background", "label": "Background", "status": "pass", "detail": "" }
    ]
  }
}

Filter with workspaceId, projectId, and templateId; paginate with offset/limit. The queue is a view over runs whose status is review, so it is always current.

POST /v1/queue/{run_id}/decision

Approve, reject, or request changes on one run.

requestbash
curl -X POST https://api.esy.com/v1/queue/run-62af77b1/decision \
  -H "Authorization: Bearer $ESY_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "decision": "reject", "note": "Glyph is clipped at the right edge." }'
FieldTypeRequiredDescription
decisionenumrequiredapprove, reject, or request_changes. The run becomes completed, rejected, or changes_requested.
notestringoptionalWhy. Kept in the decision ledger with who and when.
patchobjectoptionalRequired when releasing a typed hold, and must supply exactly the fields the hold declared.
gateIdstringoptionalWhich gate you are deciding, when a run has several.
Approval can be refused
Approving a run with any qa.checks entry at fail, or still pending, is rejected. So is a typed-hold patch with extra or missing fields, or the value "uncategorized".

POST /v1/queue/decisions

Decide several runs in one request.

requestbash
curl -X POST https://api.esy.com/v1/queue/decisions \
  -H "Authorization: Bearer $ESY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "decisions": [
      { "runId": "run-62af77b1", "decision": "approve" },
      { "runId": "run-0c7d9e21", "decision": "request_changes", "note": "Too dark." }
    ]
  }'

Each entry takes the same fields as a single decision, plus runId. The same approval rules apply to every entry individually.