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 —…
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 — events, metrics, alert rules — the build will create; no release tool for straight_to_main), the breakdown (the milestones and the items, each with its work kind and assignee) and the sources it rests on (what it read in project memory and earlier tickets, and what each settled). Submit it only after the person has answered the release question you asked with ops questions ask. The plan is recorded as drafted and waits for a person to approve it; nothing in the breakdown is filed until then. Submitting again replaces a drafted plan; an approved plan is refused with 409 (a person edits it to reopen it), except from a replan run, whose submission drafts the next revision with a summary of what changed. The open plan or replan run on the trail is closed.
The plan is checked against the trail's release facts (trails release-facts). On an autopilot trail any warning pauses autopilot and hands the plan to its owner.
Safe for the restricted ops key.
The person picked "behind a flag"; the plan run submits the plan listing the flag checkout.v2, bucketed by user with a team stage first, and the risk its error-rate alert guards.
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" \ -H "Content-Type: application/json" \ -d '{ "plan": "## Approach\\nAdd the retry queue behind `checkout.v2` and read it in the checkout handler", "release": { "strategy": "flag", "reason": "The checkout path is high traffic and the change is easy to switch off", "resources": [ { "kind": "gate", "key": "checkout.v2", "role": "ships_behind" } ], "flags": [ { "key": "checkout.v2", "bucketBy": "user", "internalFirst": true, "cleanup": "Remove the checkout.v2 flag" } ], "risks": [ { "risk": "Retries double-charge a card when the provider times out", "class": "third_party", "impact": "medium", "detect": null, "rollback": "flag", "mitigation": "Retries carry the original idempotency key" } ] } }'{
"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"
}
}
}{
"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"
}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…
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…