Link a pull request to a trail
Link a pull request to the trail as one of its *changes*. From then on the GitHub webhook records its pushes, the project's review agents score each push,…
Link a pull request to the trail as one of its changes. From then on the GitHub webhook records its pushes, the project's review agents score each push, and the merge gates read it. Linking a pull request the trail already has is a no-op; a pull request that belongs to a different trail is refused with 409. Pass item when an item's run opened the PR, so the change shows under that item.
Safe for the restricted ops key.
A coding agent working a trail opens a PR and links it with trails link-pr T-12 <url>.
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/changes" \ -H "Content-Type: application/json" \ -d '{ "prUrl": "https://github.com/acme/api/pull/41" }'{
"id": "string",
"item": {
"id": "string",
"number": 0,
"type": "bug",
"title": "string",
"status": "open"
},
"mergedAt": "string",
"mergeSha": "string",
"changedFiles": [
"string"
],
"prUrl": "string",
"prNumber": 0,
"repo": "string",
"title": "string",
"state": "open",
"headRef": "string",
"baseRef": "string",
"headSha": "string",
"mergeable": true,
"gates": [
{
"key": "up_to_date",
"label": "string",
"status": "pass",
"blocking": true,
"detail": "string"
}
],
"checks": [
{
"name": "string",
"status": "success",
"url": "string"
}
],
"evals": [
{
"agentKey": "string",
"name": "string",
"valueType": "score",
"polarity": "higher_is_better",
"threshold": 0,
"blocking": true,
"current": {
"id": "string",
"agentKey": "string",
"headSha": "string",
"status": "pending",
"value": 0,
"rationale": "string",
"reviewer": "string",
"sessionUrl": "string",
"error": "string",
"createdAt": "string",
"completedAt": "string"
},
"history": [
{
"id": "string",
"agentKey": "string",
"headSha": "string",
"status": "pending",
"value": 0,
"rationale": "string",
"reviewer": "string",
"sessionUrl": "string",
"error": "string",
"createdAt": "string",
"completedAt": "string"
}
]
}
],
"findings": [
{
"id": "string",
"agentKey": "string",
"headSha": "string",
"severity": "high",
"title": "string",
"body": "string",
"path": "string",
"line": 0,
"suggestion": "string",
"status": "open",
"stale": true,
"statusReason": "string",
"statusBy": "string",
"promotedItem": {
"id": "string",
"number": 0,
"type": "bug",
"title": "string",
"status": "open"
},
"createdAt": "string",
"updatedAt": "string"
}
],
"approvals": [
{
"id": "string",
"actorEmail": "string",
"body": "string",
"headSha": "string",
"current": true,
"actorKind": "person",
"authorizedBy": "string",
"createdAt": "string"
}
],
"pushes": [
{
"id": "string",
"headSha": "string",
"baseSha": "string",
"headRef": "string",
"baseRef": "string",
"actor": "string",
"source": "webhook",
"createdAt": "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"
}Reopen a trail
Reopen a closed trail so its changes can be reviewed and merged again. Its phase is recomputed from its changes and resources.
Unlink a pull request from a trail
Detach a pull request from the trail. Its recorded pushes, evals, findings and approvals stay in history but no longer count toward the trail's gates. A…