Approve a trail's plan
Sign off the drafted plan. Approving creates the breakdown's milestones and files its items on the trail with source plan, in one batch (itemsFiled counts…
Sign off the drafted plan. Approving creates the breakdown's milestones and files its items on the trail with source plan, in one batch (itemsFiled counts them); approving a replan files only the breakdown items not already on the trail, matched by title, and records a new revision. The build then works the items milestone by milestone, one item run each. A plan without items keeps the old shape: one trail-level build run builds it. Either way the build creates exactly the resources the plan lists and links them to the trail, and the Plan gate checks they exist. With startBuild the build is fired in the same call.
Approval is a person's call. Only a dashboard session or a device-auth CLI session can approve — ops keys, project admin keys and OAuth MCP calls are refused with 403. This operation is not exposed as an MCP tool.
The plan lists the flag and the kill switch the person asked for; approve it and start the 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/plan/approve" \ -H "Content-Type: application/json" \ -d '{ "startBuild": true }'{
"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"
}
},
"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"
}
],
"itemsFiled": 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"
}{
"error": "A resource with this name already exists in the project.",
"code": "ALREADY_EXISTS"
}{
"error": "The request body failed structural (schema) validation.",
"code": "VALIDATION"
}Edit a trail's plan
A person edits the plan text, the release block (strategy, reason, the resources to create) or the breakdown (milestones and items). Pass at least one…
List a trail's plan revisions
Every approved revision of the trail's plan, newest first: the plan as it was approved, who approved it and when, and what changed since the revision…