Shipeasy
APIOperations

List trails

Returns the project's trails, newest activity first. A trail is the unit of shipping: an outcome that takes several items, pull requests and release tools,…

Returns the project's trails, newest activity first. A trail is the unit of shipping: an outcome that takes several items, pull requests and release tools, with a lead, start and target dates, a health and a progress (items done over items on the trail). The phase, health and counts on each row are a snapshot; read one trail with trails get for the live state.

Dashboard table read. view=table is the contract every dashboard list table shares: the endpoint applies f, sort and cursor in SQL and answers { data, next_cursor, section_counts?, grouped? }. Filters and sorts are never applied in the browser, so a condition the server cannot evaluate is a 400.

  • f — a JSON array of { "f": field, "o": operator, "v": value } conditions, all ANDed. Fields are the snapshot columns: phase, status, type, priority, owner, health, targetDate, changesOpen, changesMergeable, findingsOpenHigh, itemsOpen, itemsTotal, itemsDone, releasedPct, updatedAt.
  • sort — a column id, - prefixed for descending: number, title, phase, priority, owner, health, progress (items done over items on the trail), target (the target date), changes, findings, items, released, updated, created. Defaults to -updated.
  • cursor — the previous page's next_cursor; limit is the page size (1–200, default 50).

Scopes (scope) are the dashboard's tabs: mine (trails you own), reviewing, ready, releasing, shipped, closed, or all (the default).

Attribution. mergedSince and touches list the trails that merged inside a window and changed a path or linked a resource — the candidates for an error or alert that started after a release.

Use case

Find the trail already shipping a feature before creating another, or list what merged in the last 72 hours to attribute a new alert.

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

Query Parameters

view?string

table answers the dashboard table read (f, sort, cursor, limit, section_counts, grouped). Omitted, f and sort are still honoured and the envelope is { data, next_cursor }.

Value in"table"
scope?string

A dashboard tab: mine (owned by the caller), reviewing, ready, releasing, shipped, closed, or all (the default, no narrowing).

Default"all"
Value in"all" | "mine" | "reviewing" | "ready" | "releasing" | "shipped" | "closed"
phase?string

Narrow to one phase.

Value in"planning" | "building" | "reviewing" | "ready" | "releasing" | "shipped" | "closed"
type?string

Narrow to one trail type.

Value in"feature" | "bug" | "task"
health?string

Narrow to one health (the snapshot's effective health, set or derived).

Value in"on_track" | "at_risk" | "off_track"
owner?string

Narrow to trails owned by one person OR one agent — a users.id, email or display name, or a connector id, display name or handle. Case-insensitive exact match.

q?string

Case-insensitive substring filter across the trail's title and body.

Lengthlength <= 100
mergedSince?string

ISO-8601 timestamp. Narrow to trails with a change merged at or after it.

Formatdate-time
touches?string

A file path (or path prefix) a merged change changed, or a resource key the trail links. Narrow to trails that touch it.

Lengthlength <= 500
f?string

The table's filter conditions: a JSON array of { "f", "o", "v" } objects, ANDed. See the operation description for the fields.

Lengthlength <= 8000
sort?string

A column id, - prefixed for descending (-updated). An unknown column is a 400.

Lengthlength <= 32
cursor?string

Opaque cursor returned in the previous page's next_cursor. Omit for the first page.

limit?integer

Page size (1–200). A page shorter than limit is the last one.

Default50
Range1 <= value <= 200

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://shipeasy.ai/api/admin/trails"
{
  "data": [
    {
      "id": "6f1c7d52-3a6e-4b6f-9c0e-5d9c1e7a2b10",
      "number": 12,
      "handle": "T-12",
      "title": "Retry failed webhook deliveries",
      "body": "Failed deliveries retry with backoff and surface in the delivery log",
      "type": "feature",
      "priority": "high",
      "owner": {
        "user": {
          "id": "usr_01j7w8a1b2c3d4e5f6g7h8i9j0",
          "email": "alice@acme.dev",
          "name": "Alice"
        },
        "agent": null
      },
      "status": "open",
      "closedReason": null,
      "phase": "reviewing",
      "phaseReason": "1 of 2 changes can merge",
      "origin": null,
      "repos": [
        "acme/api"
      ],
      "changesOpen": 2,
      "changesMergeable": 1,
      "findingsOpenHigh": 0,
      "itemsOpen": 1,
      "resourcesCount": 3,
      "startDate": "2026-11-02",
      "targetDate": "2026-11-20",
      "health": "on_track",
      "healthSource": "derived",
      "itemsTotal": 6,
      "itemsDone": 2,
      "goal": {
        "metric": {
          "id": "met_01j7w8k2m3n4p5q6r7s8t9v0w1",
          "key": "webhook_delivery_success_rate"
        },
        "direction": "increase",
        "baseline": 97.2,
        "target": 99.5,
        "unit": "%"
      },
      "releasedPct": null,
      "mergedAt": null,
      "shippedAt": null,
      "closedAt": null,
      "snapshotAt": "2026-11-03T10:02:44.000Z",
      "createdAt": "2026-11-02T09:14:08.000Z",
      "updatedAt": "2026-11-03T10:02:44.000Z"
    }
  ],
  "next_cursor": null
}
{
  "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 request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?