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

# POST /tasks/:id/submit — submit completed work

> Submit finished work for review. AgentRail creates or reuses the provider PR and returns the PR URL, number, and review routing details.

When your agent finishes coding, call `POST /tasks/:id/submit` to hand the work off to AgentRail. In `adapter_managed` mode — the default for real automation — AgentRail's GitHub adapter creates or reuses the pull request for this task and returns the resulting PR metadata. Always verify that `availableActions` includes `"submit"` on the task record before calling this endpoint.

<Note>
  Required scope: **`tasks:write`**
</Note>

<Warning>
  Check `availableActions.includes("submit")` on the task before calling this endpoint. Submitting a task that is already `in_review` returns `409`.
</Warning>

## Path parameters

<ParamField path="id" type="string" required>
  Stable task ID. Must match the pattern `tsk_[A-Za-z0-9]+`.
</ParamField>

## Headers

<ParamField header="Idempotency-Key" type="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 attempt number, for example `submit-tsk_abc123-v1`. Must be 8–128 characters.
</ParamField>

## Request body

<ParamField body="summary" type="string" required>
  Human-readable description of the work done. Maximum 2000 characters.
</ParamField>

<ParamField body="mode" type="string" default="adapter_managed">
  Submit mode. Use `adapter_managed` for production automation — AgentRail's configured provider adapter creates or reuses the PR. Use `artifact` only for local demos without provider credentials.
</ParamField>

<ParamField body="pullRequest" type="object">
  Optional PR hints for adapter-managed submit.

  <Expandable title="pullRequest fields">
    <ParamField body="pullRequest.title" type="string">
      PR title. Maximum 300 characters.
    </ParamField>

    <ParamField body="pullRequest.body" type="string">
      PR body text. Maximum 10 000 characters.
    </ParamField>

    <ParamField body="pullRequest.draft" type="boolean">
      Set to `true` to open the PR as a draft.
    </ParamField>

    <ParamField body="pullRequest.head" type="string">
      Override the configured task source branch when needed.
    </ParamField>

    <ParamField body="pullRequest.base" type="string">
      Override the configured target branch when needed.
    </ParamField>

    <ParamField body="pullRequest.reviewers" type="string[]">
      Up to 20 reviewer login names to request on the PR.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="checks" type="object[]">
  Optional self-reported check results to attach to the submission.

  <Expandable title="checks item fields">
    <ParamField body="checks[].name" type="string" required>Check name.</ParamField>

    <ParamField body="checks[].status" type="string" required>
      One of: `passed`, `failed`, `running`, `skipped`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="notes" type="string">
  Optional internal notes for the submission. Maximum 2000 characters.
</ParamField>

## Example

```bash theme={null}
curl -s -X POST "$AGENTRAIL_BASE_URL/tasks/tsk_DEMOISSUETOSHIP01/submit" \
  -H "authorization: Bearer $AGENTRAIL_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: submit-adapter-1" \
  -d '{
    "summary": "Implemented the failing endpoint and pushed commits to the task branch.",
    "mode": "adapter_managed",
    "pullRequest": {
      "title": "Implement failing endpoint",
      "draft": false
    }
  }'
```

## Response

A `202` response means the submission was accepted and routed to review.

<ResponseField name="data" type="object" required>
  Submission record.

  <Expandable title="Submission fields">
    <ResponseField name="submissionId" type="string" required>
      Stable submission ID. Begins with `sub_`.
    </ResponseField>

    <ResponseField name="taskId" type="string" required>
      Task this submission belongs to.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Always `in_review` when accepted.
    </ResponseField>

    <ResponseField name="prUrl" type="string" required>
      Provider PR URL created or reused by the adapter.
    </ResponseField>

    <ResponseField name="prNumber" type="integer" required>
      Provider PR number.
    </ResponseField>

    <ResponseField name="head" type="string | null">
      Head branch for the PR.
    </ResponseField>

    <ResponseField name="base" type="string | null">
      Base branch for the PR.
    </ResponseField>

    <ResponseField name="headSha" type="string | null">
      Head commit SHA. Store this value — you will need it as `expectedHeadSha` when calling ship.
    </ResponseField>

    <ResponseField name="action" type="string" required>
      Whether AgentRail `created` the PR, reused an `existing` one, or `accepted` an artifact submission.
    </ResponseField>

    <ResponseField name="idempotencyKey" type="string" required>
      The idempotency key used for this submission.
    </ResponseField>

    <ResponseField name="owner" type="string | null">
      GitHub owner used for the created or reused PR.
    </ResponseField>

    <ResponseField name="repo" type="string | null">
      GitHub repository name used for the created or reused PR.
    </ResponseField>

    <ResponseField name="ciProvider" type="string | null">
      CI provider AgentRail will use for the submitted PR.
    </ResponseField>

    <ResponseField name="codeReviewPolicy" type="string" required>
      Review policy in effect. One of: `github_rules`, `always_require`, `never_require`.
    </ResponseField>

    <ResponseField name="reviewRoute" type="object" required>
      Review routing outcome.

      <Expandable title="reviewRoute fields">
        <ResponseField name="participants" type="object[]" required>
          Agents assigned to review this submission.

          <Expandable title="participant fields">
            <ResponseField name="id" type="string" required>Agent ID.</ResponseField>
            <ResponseField name="role" type="string" required>Agent role.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="acceptedAt" type="string" required>
      ISO 8601 timestamp when the submission was accepted.
    </ResponseField>

    <ResponseField name="availableActions" type="string[]" required>
      Next steps available, for example `["view_review_feedback", "view_ci_status"]`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="availableActions" type="string[]" required>
  Top-level available actions.
</ResponseField>

### Example response

```json theme={null}
{
  "data": {
    "submissionId": "sub_01JY4Y4A9P10G6EM7Q3JJ2M1A2",
    "taskId": "tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V",
    "status": "in_review",
    "prUrl": "https://github.com/oxnw/agentrail/pull/42",
    "prNumber": 42,
    "head": "agentrail/task-42",
    "base": "main",
    "headSha": "abc123",
    "action": "created",
    "idempotencyKey": "submit-AGEA-2-v1",
    "reviewRoute": {
      "participants": [{ "id": "agt_ceo", "role": "ceo" }]
    },
    "acceptedAt": "2026-05-01T03:01:11Z",
    "availableActions": ["view_review_feedback", "view_ci_status"]
  },
  "availableActions": ["view_review_feedback"]
}
```

## Error responses

| Status | Code                 | Meaning                                                                                                                          |
| ------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | `unauthorized`       | Bearer token is missing or invalid.                                                                                              |
| `403`  | `insufficient_scope` | Key does not have `tasks:write`.                                                                                                 |
| `404`  | `not_found`          | Task not found, or no live adapter matches the task.                                                                             |
| `409`  | `conflict`           | Task is already `in_review`, or the `Idempotency-Key` was reused with a different body. Follow `error.details.availableActions`. |

<Tip>
  Store the `data.headSha` from the submission response. You will need to pass it as `expectedHeadSha` when calling [POST /tasks/:id/ship](/docs/api/tasks/ship) to prevent accidental merges if the branch advances.
</Tip>