Shipeasy
APIOperations

Ask the team questions about an item

Ask 1–4 structured questions about a queue item — the way to get a decision from a person when the implementation needs one. Each question is the…

Ask 1–4 structured questions about a queue item — the way to get a decision from a person when the implementation needs one. Each question is the AskUserQuestion shape: a short header chip, the full question, 2–4 options (label + description), and multiSelect (checkboxes instead of radios). The person can always answer "Other" in free text, so never add an "Other" option yourself. The questions render at the very top of the item's detail panel and mark the row in the queue.

Delivery. resume re-fires your trigger-connector run on the item once every question it asked is answered, continuing the same run record with the answers in the prompt — stop after asking. poll fires nothing; poll GET .../questions instead. Omitted, it is resume when runId names a run launched through a trigger connector, else poll.

On a trail. Pass the trail handle (T-12) as handle and the plan run's id as runId: a plan run asks how the trail should ship this way, and a resume answer re-fires the same plan run with the answers in its prompt. The questions render in the trail page's Plan section.

Use case

Blocked on a product decision (which behaviour to keep, which of two fixes to ship) — ask instead of guessing, then wait for the answer.

POST
/api/admin/ops/{handle}/questions

Authorization

bearerSdkKey
AuthorizationBearer <token>

Pass an admin SDK key as Authorization: Bearer sdk_admin_…. Mint via POST /api/admin/keys with type: "admin".

In: header

Path Parameters

handle*string

Per-project item number (e.g. 7) or the full ops item id, or a trail handle (e.g. T-12) for a question on a trail.

Length1 <= length <= 128

Header Parameters

X-Project-Id?string

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

curl -X POST "https://shipeasy.ai/api/admin/ops/string/questions" \  -H "Content-Type: application/json" \  -d '{    "runId": "0d3f4c8e-7a51-4c2e-9b1f-1e2d3c4b5a69",    "questions": [      {        "header": "Legacy param",        "question": "Should the fix keep honouring the legacy `?v=1` query param?",        "multiSelect": false,        "options": [          {            "label": "Keep it",            "description": "Old links keep working; the redirect stays"          },          {            "label": "Drop it",            "description": "Simpler code; old links land on the default view"          }        ]      }    ]  }'
[
  {
    "id": "string",
    "feedbackId": "string",
    "trailId": "string",
    "header": "string",
    "question": "string",
    "options": [
      {
        "label": "string",
        "description": "string"
      }
    ],
    "multiSelect": true,
    "status": "open",
    "answer": {
      "selected": [
        "string"
      ],
      "other": "string"
    },
    "answeredBy": "string",
    "answeredAt": "string",
    "agent": "jarvis",
    "askedBy": "string",
    "runId": "string",
    "delivery": "resume",
    "deliveredAt": "string",
    "deliveryError": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
]
{
  "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": "The request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?