Shipeasy
APIOperations

Promote a finding to a queue item

Move a finding that is real but out of scope onto the queue. It creates a bug (or a feature request, with type) whose description quotes the finding, its…

Move a finding that is real but out of scope onto the queue. It creates a bug (or a feature request, with type) whose description quotes the finding, its path and line, and its push. The new item lands on the trail with source finding, and the finding is dismissed as moved to #N so the gates stop counting it. Promotion is the one-way bridge from a finding (per push, in scope, must be dealt with before merge) to an item (lives on its own, can become its own trail).

Safe for the restricted ops key.

Use case

A review flags a flaky test unrelated to the change; the coding agent promotes it instead of drive-by fixing it.

POST
/api/admin/trails/{handle}/findings/{findingId}/promote

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

The trail's handle (T-12) or its id.

Match^(?:T-[0-9]+|[0-9a-fA-F-]{32,36})$
Length1 <= length <= 64
findingId*string

The finding id.

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

application/json

curl -X POST "https://shipeasy.ai/api/admin/trails/string/findings/string/promote" \  -H "Content-Type: application/json" \  -d '{    "reason": "Pre-existing flake in the webhook suite, unrelated to the retry change",    "type": "bug"  }'
{
  "item": {
    "item": {
      "id": "string",
      "number": 0,
      "type": "bug",
      "title": "string",
      "status": "open"
    },
    "priority": "nice_to_have",
    "discoveredSource": "origin",
    "discoveredSha": "string",
    "change": {
      "id": "string",
      "prUrl": "string",
      "prNumber": 0,
      "repo": "string"
    },
    "milestoneId": "string",
    "workKind": "code"
  },
  "finding": {
    "id": "string",
    "agentKey": "string",
    "headSha": "string",
    "severity": "high",
    "title": "string",
    "body": "string",
    "path": "string",
    "line": 0,
    "suggestion": "string",
    "status": "open",
    "stale": true,
    "statusReason": "string",
    "statusBy": "string",
    "promotedItem": {
      "id": "string",
      "number": 0,
      "type": "bug",
      "title": "string",
      "status": "open"
    },
    "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": "A resource with this name already exists in the project.",
  "code": "ALREADY_EXISTS"
}

{
  "error": "The request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?