Shipeasy
APIOperations

Create a trail

Creates a trail in planning. A trail is created on purpose — nothing makes one implicitly. Create one from scratch with a title and a body (the outcome and…

Creates a trail in planning. A trail is created on purpose — nothing makes one implicitly. Create one from scratch with a title and a body (the outcome and the acceptance criteria), or press Ship this on a queue item with originItem: the item's description seeds the body and the item becomes the trail's first item, with source origin. An item is on at most one trail.

A trail may carry a goal (the metric it is meant to move, with a baseline and a target), a startDate and a targetDate, and a health set by hand (omitted, it is derived).

Fire the project's coding agent on the new trail with trails start, or link pull requests an agent already opened with trails link-pr.

Autopilot. autopilot: { enabled: true, limits } turns on autopilot at creation: the plan's questions are answered with the agent's recommendation, the plan is approved, and the change merges when every blocking gate is green, all inside the limits. It needs the autopilot capability and a person's identity (a dashboard session or a signed-in CLI); an ops key, an admin key or MCP asking for it is refused with 403. Everything else is safe for the restricted ops key.

Use case

A coding agent that was asked to ship a multi-part feature opens one trail for it, then links every PR it opens.

POST
/api/admin/trails

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

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 POST "https://shipeasy.ai/api/admin/trails" \  -H "Content-Type: application/json" \  -d '{    "title": "Retry failed webhook deliveries",    "body": "Failed deliveries retry with backoff, and the delivery log shows every attempt.\\n\\nAcceptance:\\n- 5 attempts over 24 hours\\n- a failed final attempt files an alert",    "type": "feature",    "priority": "high",    "repos": [      "acme/api"    ]  }'
{
  "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": "A resource with this name already exists in the project.",
  "code": "ALREADY_EXISTS"
}

{
  "error": "The request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?