Show a trail
A trail followed from intent to release: its phase, every change (each a pull request) with its latest push, merge gates, CI checks, each review agent's…
A trail followed from intent to release: its phase, every change (each a pull request) with its latest push, merge gates, CI checks, each review agent's eval next to its last five, every finding (open first, worst first, stale when raised on an earlier push), approvals and pushes; the items discovered on it; the product resources it ships with their live state; the runs working it; and the suspected regressions awaiting a person.
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. Phase and counts are recomputed live. Pass files to include each merged change's full changed-file list and the diff link.
Safe for the restricted ops key.
After pushing a fix, a coding agent reads the trail to see which findings are still open and whether the scores have turned green.
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
The trail's handle (T-12) or its id.
^(?:T-[0-9]+|[0-9a-fA-F-]{32,36})$1 <= length <= 64Query Parameters
Include each merged change's full changedFiles list. Omitted, changedFiles is null.
falseHeader 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).
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://shipeasy.ai/api/admin/trails/string"{
"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": "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"
}Create a trail
Creates a trail in planning. A trail is created on purpose — nothing makes one implicitly. Create one from scratch with a title and a body (the outcome and…
Change a trail
Change a trail's title, intent, type, priority, owner (the lead), repo scope, start and target dates, health, goal or autopilot. Pass at least one field;…