Start an agent on a trail
Fire the project's coding-agent trigger on the trail. Once the plan is approved (trails approve-plan), starting an agent builds it. Where the project turned…
Fire the project's coding-agent trigger on the trail. Once the plan is approved (trails approve-plan), starting an agent builds it. Where the project turned plan approval off (trail-gates requirePlan), the plan run asks nothing and a plan with no warnings approves itself and starts the build.
Build. When the approved plan filed items, build launches an item run for every open item of the first milestone that still has open items and no run working it (items without a milestone count as the first), at most trail-gates maxParallelRuns (default 3) at once, and no trail-level build run: run is null and itemRuns says what happened to each item. Each item run opens its own pull request, which becomes a change of the trail. Otherwise one trail-level build run carries the plan to pull requests, creates exactly the resources the plan lists and links them, as before, and itemRuns is empty.
Replan. Once a plan is approved, kind: replan fires a read-only run that re-reads the goal metric, the items' outcomes and project memory and submits the plan's next revision, which waits as drafted for approval.
fix runs are fired by the server when a change's evals or findings fail. Pass kind to ask for one explicitly. Runs spend your own agent quota, not Shipeasy credits.
A trail is created from a feature request; start an agent on it to plan it, approve the plan, then start it again to build.
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 <= 64Header 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).
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/runs" \ -H "Content-Type: application/json" \ -d '{ "agent": "claude" }'{
"run": {
"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"
},
"itemRuns": [
{
"item": {
"id": "string",
"number": 0,
"type": "bug",
"title": "string",
"status": "open"
},
"launched": true,
"reason": "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"
}Unlink a pull request from a trail
Detach a pull request from the trail. Its recorded pushes, evals, findings and approvals stay in history but no longer count toward the trail's gates. A…
Submit a trail's plan
A plan run submits what it worked out: the plan in markdown, the release block (how the trail ships, why, and the exact flags, kill switches and tracking —…