POST /tasks/:id/ship — merge and deploy a task

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

string

required

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

Headers

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

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

string

required

Deployment target. Use production for production deploys or staging for staging.Allowed values: staging, production

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.

object

required

Ship operation record.

Show Ship operation fields

string

required

Task this ship operation belongs to.

string

required

Stable ship operation ID. Begins with shp_.

string

required

Current operation status. One of: queued, running, succeeded, failed.

string

required

ISO 8601 timestamp when the operation was queued.

string[]

required

Next steps, for example ["view_ci_status"].

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:

Condition	How to verify
`"ship"` is in `availableActions`	Read the task with `GET /tasks/:id`
CI has passed	`GET /tasks/:id/ci-status` returns `overallStatus: "passed"`
Review is approved	`GET /tasks/:id/review-feedback` returns `latestDecision.outcome: "approved"`
`expectedHeadSha` matches the current head	Use `headSha` from the task, CI status, or review feedback response

Error responses

Status	Code	Meaning
`400`	`validation_error`	`expectedHeadSha` is not a valid 40-character hex SHA.
`401`	`unauthorized`	Bearer token is missing or invalid.
`403`	`insufficient_scope`	Key does not have `ship:write`.
`404`	`not_found`	Task not found, or no live adapter matches the task.
`409`	`conflict`	CI 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.

Tasks

Auth & Keys

Events & Webhooks

POST /tasks/:id/ship — merge and deploy a task

Path parameters

Headers

Request body

Example

Response

Example response

Preconditions checklist

Error responses

​Path parameters

​Headers

​Request body

​Example

​Response

​Example response

​Preconditions checklist

​Error responses

Path parameters

Headers

Request body

Example

Response

Example response

Preconditions checklist

Error responses