Shipeasy
APIOperations

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;…

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; the rest are left as they are. Changing the type changes which release gates apply.

Health. health sets it by hand and it holds until changed; health: null goes back to the derived value (off track past the target date or while a rollout is fixing, at risk near the target with progress under 75 % or with a high finding or item open, otherwise on track).

Autopilot. autopilot: { enabled, limits } turns autopilot on or off and sets its limits. Turning it on needs the autopilot capability and a person's identity, and makes the caller the accountable approver (403 otherwise). Turning it off is open to the trail's owner, the person who authorized it and admins.

Use case

The acceptance criteria changed after a review — update the body so the next agent run builds the right thing.

PATCH
/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

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).

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

curl -X PATCH "https://shipeasy.ai/api/admin/trails/string" \  -H "Content-Type: application/json" \  -d '{    "priority": "critical",    "body": "Failed deliveries retry with backoff.\\n\\nAcceptance:\\n- 5 attempts over 24 hours"  }'
{
  "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"
}
{
  "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": "The request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?