Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

When CI passes and review is approved, call POST /tasks/:id/ship to merge the PR and deploy the changes. AgentRail validates all preconditions before accepting the request. You must supply expectedHeadSha to prevent accidental merges if the branch has advanced since you last read the task. Always gate this call on availableActions.includes("ship") — if "ship" is not in the list, the task is not ready.
Required scope: ship:write
Never call ship without first verifying that CI has passed, review is approved, and availableActions includes "ship". Calling ship when these conditions are not met returns 409. Passing an incorrect expectedHeadSha also returns 409.

​
Path parameters

​
id
string
required
Stable task ID. Must match the pattern tsk_[A-Za-z0-9]+.

​
Headers

​
Idempotency-Key
string
required
Unique key for safe retries. The same key plus the same request body replays the original accepted result. The same key with a different body returns 409 conflict. Use a key that encodes the task ID and head SHA, for example ship-tsk_abc123-b5bc7f8. Must be 8–128 characters.

​
Request body

​
mode
string
required
Ship mode. Use merge_and_deploy to merge the PR and trigger deployment. Use merge_only to merge without deploying.Allowed values: merge_only, merge_and_deploy
​
targetEnvironment
string
required
Deployment target. Use production for production deploys or staging for staging.Allowed values: staging, production
​
expectedHeadSha
string
required
The full 40-character commit SHA you expect to be at the head of the task branch. AgentRail rejects the request with 409 if the actual head SHA differs, preventing accidental merges after a late commit. Read this value from data.headSha on the task, or from the CI status or review feedback responses.

​
Example

curl -s -X POST "$AGENTRAIL_BASE_URL/tasks/tsk_DEMOISSUETOSHIP01/ship" \
  -H "authorization: Bearer $AGENTRAIL_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: ship-demo-1" \
  -d '{
    "mode": "merge_and_deploy",
    "targetEnvironment": "production",
    "expectedHeadSha": "b5bc7f86b9ad94f4f18f83d28bdf3e27a31e53a0"
  }'

​
Response

A 202 response means the ship operation was accepted and queued.
​
data
object
required
Ship operation record.
​
availableActions
string[]
required
Top-level available actions.

​
Example response

{
  "data": {
    "taskId": "tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V",
    "operationId": "shp_01JY4YP2N9PTDP8PHV7ZV8B7XS",
    "status": "queued",
    "queuedAt": "2026-05-01T03:12:02Z",
    "availableActions": ["view_ci_status"]
  },
  "availableActions": ["view_ci_status"]
}

​
Preconditions checklist

All of the following must be true before AgentRail accepts a ship request:
ConditionHow to verify
"ship" is in availableActionsRead the task with GET /tasks/:id
CI has passedGET /tasks/:id/ci-status returns overallStatus: "passed"
Review is approvedGET /tasks/:id/review-feedback returns latestDecision.outcome: "approved"
expectedHeadSha matches the current headUse headSha from the task, CI status, or review feedback response

​
Error responses

StatusCodeMeaning
400validation_errorexpectedHeadSha is not a valid 40-character hex SHA.
401unauthorizedBearer token is missing or invalid.
403insufficient_scopeKey does not have ship:write.
404not_foundTask not found, or no live adapter matches the task.
409conflictCI is not green, review is not approved, the task is not in a shippable state, the head SHA does not match, or the Idempotency-Key was reused with a different body.
If you receive 409 because of a SHA mismatch, re-read the task with GET /tasks/:id to get the updated headSha, then retry with a new Idempotency-Key that encodes the new SHA.