Ack an item (start a run)
Acknowledge a queue item — a person or an AI agent declaring "I'm on this now". Opens a run: stamps who picked the item up and when, assigns them as owner,…
Acknowledge a queue item — a person or an AI agent declaring "I'm on this
now". Opens a run: stamps who picked the item up and when, assigns them as
owner, and moves the item into the matching working status
(investigating_by_ai for an AI ack, in_progress for a human one). The
dashboard renders the open run as a live working indicator (which agent +
time since the run started).
AI ack. Pass agent with your own agent type (claude, cursor,
copilot, jules; gemini is also accepted and is normalized to jules on receipt) and, when you have one, the
run's sessionId so the dashboard can deep-link to the session. If the
project has no connected trigger connector of that type the call fails
with AGENT_NOT_CONNECTED — list the available agents with ops agents list and use one of those (or connect the agent under Settings →
Triggers).
Launching. When the named agent has a connected trigger and you pass
no sessionId, the ack also fires that trigger — a new provider run
starts working the item. Pass launch: false to only claim the item and
record the run (you are doing the work yourself), without starting one.
A launch on an item linked to others (see group on ops get) is only
allowed on the group's master — any other member answers 409
INVALID_TRANSITION, naming the master to ack instead.
Completion. The run closes automatically on the loop's final actions —
linking the fixing PR (link-pr), an ops-notify escalation, or a
completion status change (ready_for_qa/resolved) — and the dashboard
then shows the run result (final action, PR, duration, session link).
One session per item. An AI ack on an item whose open run belongs to
another live agent session answers 409 ALREADY_EXISTS, naming that
run — skip the item, the other session is working it. Your own run is
adopted, not refused: re-ack with its runId (a fired run's prompt names
it; a previous ack returned it) or the same sessionId. A run a trigger
fire claimed is adopted by the FIRST session to ack it. A run silent past
the stuck-run threshold (6h), or takeover: true, is superseded instead.
A human ack never replaces an open agent run.
Call this first when picking an item up, so the team sees who/what is working on it in real time.
Authorization
bearerSdkKey Pass an admin SDK key as Authorization: Bearer sdk_admin_…. Mint via POST /api/admin/keys with type: "admin".
In: header
Path Parameters
Per-project item number (e.g. 7) or the full ops item id.
1 <= length <= 128Header Parameters
Project the request operates on. Optional — defaults to the project the SDK key belongs to; pass it only to scope a multi-project key (the generated client sets it once from its configuration, so per-call callers never thread it).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://shipeasy.ai/api/admin/ops/string/ack" \ -H "Content-Type: application/json" \ -d '{ "agent": "claude", "sessionId": "session_01CiaFDeDyr37JZ62Gzd8oir" }'{
"id": "fb_01j7w8a1b2c3d4e5f6g7h8i9j0",
"number": 7,
"status": "investigating_by_ai",
"runId": "6f1f9a1e-8b32-4c8e-9a51-2f3b1c9d0e4a",
"agent": "claude",
"connectorName": "Claude",
"sessionId": "session_01CiaFDeDyr37JZ62Gzd8oir",
"startedAt": "2026-07-17T10:15:00.000Z"
}{
"error": "Malformed request (bad JSON, missing project scope).",
"code": "BAD_REQUEST"
}{
"error": "Missing or invalid admin SDK key.",
"code": "UNAUTHORIZED"
}{
"error": "Key is valid but not allowed to act on this project.",
"code": "FORBIDDEN"
}{
"error": "The resource does not exist or is not visible to the caller.",
"code": "NOT_FOUND"
}{
"error": "A resource with this name already exists in the project.",
"code": "ALREADY_EXISTS"
}{
"error": "The request body failed structural (schema) validation.",
"code": "VALIDATION"
}Update a linked group
Applies status and/or priority to every item in this item's link group — the items tied to it, directly or through a chain, by blocked-by / blocking /…
List an item's investigation records
The structured, read-only investigation records on a queue item — the findings / blocking questions / QA notes an AI agent posted while working it, plus its…