---
title: "Record a verified landing"
method: POST
path: "/v1/tasks/{id}/land"
tags: ["Board"]
---

# Record a verified landing

`POST /v1/tasks/{id}/land`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/tasks/{id}/land`
- Auth: HTTP bearer

After the task’s result was merged and checked, records it: `sha`, the result commit, is contained in `into`, the project’s default branch on the project hub. The task then shows `landed`, its land item leaves Needs you and its master hears it. This route merges nothing: the Shard app and `shard task land` merge first (into the person’s linked folder too), check, then call it. `branch` is the task’s result branch, shard/<task id>. 409 `task_not_done` before the master’s done report; 409 `result_changed` when the master sealed a newer result (`report_id`) since.

## Path parameters

- `id` string, required

## Request body

- object
  - `sha` string, required
  - `into` string, required
  - `branch` string, required
  - `report_id` string: The done report whose result was merged (the task’s current result when left out).
  - `conversation_ids` string[]: Workers whose branches were checked to be in `sha`: they read as merged into `into`.
  - `organization_id` string, uuid: UUIDv7, lowercase canonical form.

## Response `200`

Default Response

- object
  - `task` Task, required
    - `id` string, required
    - `project_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `home` boolean, required: A personal task: it runs on the project’s machine home, without a repository.
    - `text` string, required: The person’s exact words. Never rewritten.
    - `title` string, nullable, required: A short title; null until it arrives (show `text` meanwhile).
    - `waiting` object, nullable, required: Set while the task waits to start or continue (no linked agent is running); null otherwise. `until`: when the wait ends by itself (a usage reset), to show in local time.
      - `reason` string, required: Why the task waits for its agent: usage_limit, capacity_wait, agent_not_running, …
      - `message` string, required: One line for the row, in plain words: “Getting its computer ready”, “Waiting for a free computer”, “Claude usage resets 15:00 UTC”.
      - `since` string, date-time, required: RFC 3339 UTC timestamp with Z.
      - `until` string, date-time, nullable: RFC 3339 UTC timestamp with Z.
    - `activity` string, nullable, required: Working: what it is doing now, one line, from its working conversation (a worker before the master); null otherwise. Changes arrive through the feed.
    - `bucket` 'now' | 'next' | 'later', required
    - `position` number, required: Order within the bucket: lower comes first.
    - `state` 'queued' | 'working' | 'needs_you' | 'done' | 'unverified' | 'failed', required
    - `parent_task_id` string, nullable, required
    - `suggested` boolean, required: Proposed by an agent; it sits in Later until the person keeps it.
    - `harness` 'claude' | 'codex', nullable, required
    - `master_id` string, nullable, required
    - `conversations` object[], required: The conversations that work on it: the master first, then its workers.
      - `id` string, required
      - `role` 'master' | 'builder' | 'reviewer' | 'light' | 'hard' | 'worker', required
      - `step_id` string, nullable, required
    - `plan` object, nullable, required
      - `summary` string, required
      - `steps` object[], required
        - `id` string, required
        - `text` string, required
        - `state` 'queued' | 'working' | 'done' | 'failed', required
        - `conversation_id` string, nullable, required
        - `outcome` string, nullable, required: Done: the one-line outcome of the report that finished it.
        - `evidence` string[], required: Done: that report’s evidence labels.
        - `report_id` string, nullable, required
        - `now` string, nullable, required: Working: what its conversation is doing now, one line (its live title); null otherwise.
    - `landed` object, nullable, required: Where the task’s current result landed (the commit and the branch it is in); null until it did. Done and landed is shipped.
      - `sha` string, required: The result commit, contained in `into`.
      - `into` string, required: The branch it landed in: the project’s default branch on the project hub.
      - `branch` string, required: The task’s result branch (shard/<task id>), where its master merged its workers’ branches.
      - `at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `latest_report_id` string, nullable, required
    - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `updated_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `seen_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `cleared_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `deleted_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)