Shipeasy
APIOperations

Show an item's trail

Alias. Kept for the v1 item routes: it resolves the item's trail and behaves exactly like GET /api/admin/trails/{handle}, answering 404 when the item is on…

Alias. Kept for the v1 item routes: it resolves the item's trail and behaves exactly like GET /api/admin/trails/{handle}, answering 404 when the item is on no trail. Prefer the /api/admin/trails routes. Not part of the CLI or MCP surface.

The item's trail, followed from intent to release: its phase, and for every pull request (each a change) the latest push, the merge gates and how they read, CI checks, each review agent's eval on the latest push next to its last five, every finding (open first, worst first, stale when raised on an earlier push), the approvals, and the pushes.

Gates are read live from GitHub on every call, so a state of unknown means GitHub could not be read and the PR-backed gates read pending.

Use case

After pushing a fix, a coding agent reads the trail to see which findings are still open and whether the scores have turned green.

GET
/api/admin/ops/{handle}/trail

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.

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).

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://shipeasy.ai/api/admin/ops/string/trail"
{
  "id": "string",
  "number": 0,
  "handle": "string",
  "title": "string",
  "body": "string",
  "type": "feature",
  "priority": "nice_to_have",
  "owner": {
    "user": {
      "id": "string",
      "email": "string",
      "name": "string"
    },
    "agent": {
      "connectorId": "string",
      "builtin": "jarvis",
      "provider": "claude_trigger",
      "name": "string"
    }
  },
  "status": "open",
  "closedReason": "string",
  "phase": "planning",
  "phaseReason": "string",
  "origin": {
    "id": "string",
    "number": 0,
    "type": "bug",
    "title": "string",
    "status": "open"
  },
  "repos": [
    "string"
  ],
  "changesOpen": 0,
  "changesMergeable": 0,
  "findingsOpenHigh": 0,
  "itemsOpen": 0,
  "resourcesCount": 0,
  "startDate": "2019-08-24",
  "targetDate": "2019-08-24",
  "health": "on_track",
  "healthSource": "person",
  "itemsTotal": 0,
  "itemsDone": 0,
  "goal": {
    "metric": {
      "id": "string",
      "key": "string"
    },
    "direction": "increase",
    "baseline": 0,
    "target": 0,
    "unit": "string"
  },
  "releasedPct": 0,
  "mergedAt": "string",
  "shippedAt": "string",
  "closedAt": "string",
  "snapshotAt": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "changes": [
    {
      "id": "string",
      "item": {
        "id": "string",
        "number": 0,
        "type": "bug",
        "title": "string",
        "status": "open"
      },
      "mergedAt": "string",
      "mergeSha": "string",
      "changedFiles": [
        "string"
      ],
      "prUrl": "string",
      "prNumber": 0,
      "repo": "string",
      "title": "string",
      "state": "open",
      "headRef": "string",
      "baseRef": "string",
      "headSha": "string",
      "mergeable": true,
      "gates": [
        {
          "key": "up_to_date",
          "label": "string",
          "status": "pass",
          "blocking": true,
          "detail": "string"
        }
      ],
      "checks": [
        {
          "name": "string",
          "status": "success",
          "url": "string"
        }
      ],
      "evals": [
        {
          "agentKey": "string",
          "name": "string",
          "valueType": "score",
          "polarity": "higher_is_better",
          "threshold": 0,
          "blocking": true,
          "current": {
            "id": "string",
            "agentKey": "string",
            "headSha": "string",
            "status": "pending",
            "value": 0,
            "rationale": "string",
            "reviewer": "string",
            "sessionUrl": "string",
            "error": "string",
            "createdAt": "string",
            "completedAt": "string"
          },
          "history": [
            {
              "id": "string",
              "agentKey": "string",
              "headSha": "string",
              "status": "pending",
              "value": 0,
              "rationale": "string",
              "reviewer": "string",
              "sessionUrl": "string",
              "error": "string",
              "createdAt": "string",
              "completedAt": "string"
            }
          ]
        }
      ],
      "findings": [
        {
          "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"
        }
      ],
      "approvals": [
        {
          "id": "string",
          "actorEmail": "string",
          "body": "string",
          "headSha": "string",
          "current": true,
          "actorKind": "person",
          "authorizedBy": "string",
          "createdAt": "string"
        }
      ],
      "pushes": [
        {
          "id": "string",
          "headSha": "string",
          "baseSha": "string",
          "headRef": "string",
          "baseRef": "string",
          "actor": "string",
          "source": "webhook",
          "createdAt": "string"
        }
      ]
    }
  ],
  "items": [
    {
      "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"
    }
  ],
  "milestones": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "targetDate": "2019-08-24",
      "position": 0,
      "itemsTotal": 0,
      "itemsDone": 0,
      "late": true
    }
  ],
  "resources": [
    {
      "id": "string",
      "kind": "gate",
      "resourceId": "string",
      "resourceKey": "string",
      "role": "ships_behind",
      "source": "agent",
      "state": {
        "exists": true,
        "archived": true,
        "settled": true,
        "summary": "string",
        "prodRolloutPct": 0,
        "status": "string",
        "decision": "string",
        "property1": null,
        "property2": null
      },
      "createdAt": "string"
    }
  ],
  "runs": [
    {
      "id": "string",
      "kind": "build",
      "state": "launching",
      "agent": "string",
      "sessionUrl": "string",
      "change": {
        "id": "string",
        "prUrl": "string",
        "prNumber": 0,
        "repo": "string"
      },
      "headSha": "string",
      "summary": "string",
      "startedAt": "string",
      "completedAt": "string",
      "error": "string"
    }
  ],
  "suspects": [
    {
      "id": "string",
      "item": {
        "id": "string",
        "number": 0,
        "type": "bug",
        "title": "string",
        "status": "open"
      },
      "confidence": "high",
      "evidence": "string",
      "status": "pending",
      "attributedBy": "string",
      "source": "post_merge",
      "createdAt": "string"
    }
  ],
  "gates": {
    "upToDate": {
      "enabled": true,
      "blocking": true
    },
    "humanReview": {
      "enabled": true,
      "blocking": true,
      "minApprovals": 1,
      "resetOnPush": true,
      "authorCanApprove": false
    },
    "agentReview": {
      "enabled": true,
      "blocking": true,
      "severity": "high"
    },
    "evals": {
      "enabled": true,
      "blocking": true
    },
    "checks": {
      "enabled": true,
      "blocking": true,
      "required": [
        "string"
      ]
    },
    "discovered": {
      "enabled": true,
      "blocking": true,
      "priority": "nice_to_have"
    },
    "shipsDark": {
      "enabled": false,
      "blocking": false
    },
    "rollback": {
      "enabled": false,
      "blocking": false
    },
    "measured": {
      "enabled": false,
      "blocking": false
    },
    "guarded": {
      "enabled": false,
      "blocking": false
    },
    "copy": {
      "enabled": false,
      "blocking": false
    },
    "plan": {
      "enabled": true,
      "blocking": true
    },
    "requirePlan": true,
    "fixRounds": 3,
    "goalWindowDays": 7,
    "maxGoalReplans": 3,
    "maxParallelRuns": 3,
    "attributionWindowHours": 72,
    "rollout": {
      "steps": [
        1,
        5,
        25,
        50,
        100
      ],
      "holdMinutes": 0,
      "minExposure": 0,
      "internal": {
        "holdMinutes": 0
      },
      "guards": {
        "alertRuleIds": [
          "string"
        ],
        "attributedErrors": true
      },
      "policies": {
        "onBreach": "pull_back",
        "breachTimeoutMinutes": 1,
        "advance": "auto",
        "afterFix": "resume"
      }
    },
    "autopilot": {
      "maxRisk": 0,
      "repos": [
        "string"
      ],
      "types": [
        "feature"
      ],
      "maxFixRounds": 0,
      "maxPullBacks": 0,
      "maxRuns": 0
    },
    "intakeMatching": true,
    "repos": {
      "property1": {
        "checks": {
          "required": [
            "string"
          ]
        }
      },
      "property2": {
        "checks": {
          "required": [
            "string"
          ]
        }
      }
    }
  },
  "plan": {
    "status": "none",
    "plan": "string",
    "release": {
      "strategy": "straight_to_main",
      "reason": "string",
      "resources": [
        {
          "kind": "gate",
          "key": "string",
          "role": "ships_behind",
          "rollout": {
            "steps": [
              1,
              5,
              25,
              50,
              100
            ],
            "holdMinutes": 0,
            "minExposure": 0,
            "internal": {
              "holdMinutes": 0
            },
            "guards": {
              "alertRuleIds": [
                "string"
              ],
              "attributedErrors": true
            },
            "policies": {
              "onBreach": "pull_back",
              "breachTimeoutMinutes": 1,
              "advance": "auto",
              "afterFix": "resume"
            }
          }
        }
      ],
      "rollout": {
        "steps": [
          1,
          5,
          25,
          50,
          100
        ],
        "holdMinutes": 0,
        "minExposure": 0,
        "internal": {
          "holdMinutes": 0
        },
        "guards": {
          "alertRuleIds": [
            "string"
          ],
          "attributedErrors": true
        },
        "policies": {
          "onBreach": "pull_back",
          "breachTimeoutMinutes": 1,
          "advance": "auto",
          "afterFix": "resume"
        }
      },
      "flags": [
        {
          "key": "string",
          "bucketBy": "user",
          "internalFirst": true,
          "internalSkipReason": "string",
          "cleanup": "string"
        }
      ],
      "risks": [
        {
          "risk": "string",
          "class": "load",
          "impact": "low",
          "detect": "string",
          "rollback": "flag",
          "mitigation": "string"
        }
      ]
    },
    "breakdown": {
      "milestones": [
        {
          "name": "string",
          "targetDate": "2019-08-24"
        }
      ],
      "items": [
        {
          "title": "string",
          "type": "bug",
          "priority": "nice_to_have",
          "body": "string",
          "milestone": "string",
          "assignee": "string",
          "workKind": "code",
          "creates": [
            "string"
          ],
          "shipsDark": true
        }
      ]
    },
    "marketing": {
      "summary": "string",
      "channels": [
        {
          "channel": "blog",
          "title": "string",
          "timing": "string",
          "brief": "string"
        }
      ]
    },
    "sources": [
      {
        "kind": "memory",
        "ref": "string",
        "note": "string"
      }
    ],
    "revision": 0,
    "approvedBy": "string",
    "approvedAt": "string",
    "requirePlan": true,
    "nextRun": "plan",
    "openQuestions": 0,
    "checks": {
      "warnings": [
        "string"
      ],
      "facts": {
        "proxy": {
          "kind": "metric",
          "key": "string"
        },
        "tier": "none",
        "unitsPerDay": 0,
        "rollout": {
          "internal": {
            "holdMinutes": 0
          },
          "steps": [
            0
          ],
          "holdMinutes": 0,
          "minExposure": 0
        },
        "notes": [
          "string"
        ]
      },
      "checkedAt": "string"
    }
  },
  "rollout": {
    "resource": {
      "id": "string",
      "key": "string"
    },
    "state": "idle",
    "config": {
      "steps": [
        1,
        5,
        25,
        50,
        100
      ],
      "holdMinutes": 0,
      "minExposure": 0,
      "internal": {
        "holdMinutes": 0
      },
      "guards": {
        "alertRuleIds": [
          "string"
        ],
        "attributedErrors": true
      },
      "policies": {
        "onBreach": "pull_back",
        "breachTimeoutMinutes": 1,
        "advance": "auto",
        "afterFix": "resume"
      }
    },
    "step": 0,
    "stepPct": 0,
    "stepStartedAt": "string",
    "pausedReason": "string",
    "pending": {
      "kind": "breach",
      "questionId": "string",
      "askedAt": "string"
    }
  },
  "rollouts": [
    {
      "resource": {
        "id": "string",
        "key": "string"
      },
      "state": "idle",
      "config": {
        "steps": [
          1,
          5,
          25,
          50,
          100
        ],
        "holdMinutes": 0,
        "minExposure": 0,
        "internal": {
          "holdMinutes": 0
        },
        "guards": {
          "alertRuleIds": [
            "string"
          ],
          "attributedErrors": true
        },
        "policies": {
          "onBreach": "pull_back",
          "breachTimeoutMinutes": 1,
          "advance": "auto",
          "afterFix": "resume"
        }
      },
      "step": 0,
      "stepPct": 0,
      "stepStartedAt": "string",
      "pausedReason": "string",
      "pending": {
        "kind": "breach",
        "questionId": "string",
        "askedAt": "string"
      }
    }
  ],
  "autopilot": {
    "state": "off",
    "authorizedBy": "string",
    "authorizedAt": "string",
    "pausedReason": "string",
    "limits": {
      "maxRisk": 0,
      "repos": [
        "string"
      ],
      "types": [
        "feature"
      ],
      "maxFixRounds": 0,
      "maxPullBacks": 0,
      "maxRuns": 0
    },
    "runsUsed": 0
  },
  "releaseEvents": [
    {
      "id": "string",
      "kind": "started",
      "resource": {
        "id": "string",
        "key": "string"
      },
      "step": 0,
      "fromPct": 0,
      "toPct": 0,
      "reason": "string",
      "evidence": {},
      "actor": "string",
      "createdAt": "string"
    }
  ],
  "goalStatus": {
    "state": "none",
    "watchFrom": "string",
    "judgeAt": "string",
    "value": 0,
    "replans": 0,
    "maxReplans": 0
  }
}
{
  "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"
}
Was this page helpful?