Shipeasy
APIOperations

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.

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/trails/{handle}

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

Query Parameters

files?boolean

Include each merged change's full changedFiles list. Omitted, changedFiles is null.

Defaultfalse

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

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"
}
Was this page helpful?