---
title: "Record a completed landing action"
method: POST
path: "/v1/conversations/{id}/land"
tags: ["Conversations"]
---

# Record a completed landing action

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

## Request

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

## Path parameters

- `id` string, required

## Request body

- object
  - `action` 'merge' | 'pr' | 'keep' | 'discard', required
  - `into` string

## Response `200`

Default Response

- Conversation
  - `id` string, required
  - `project_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `key` string, required
  - `name` string, required
  - `title` string, required
  - `summary` string, required
  - `harness` 'claude' | 'codex', required
  - `harness_session_id` string, nullable, required
  - `route` 'terminal' | 'acp' | 'codex-app' | 'codex-cloud' | 'claude-desktop' | 't3-ssh', required
  - `role` 'main' | 'fork' | 'spawn' | 'join', required
  - `join_mode` 'reviewer' | 'worker', nullable, required
  - `orchestrator_conversation_id` string, nullable
  - `orchestrator_input_id` string, nullable
  - `settled_reason` 'computer_suspended' | 'computer_failed', nullable: The computer suspended or failed while a native turn was active. Cleared by later live activity. Null or absent does not establish that a turn finished.
  - `parent_id` string, nullable, required
  - `root_id` string, required
  - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `worktree_path` string, required
  - `branch` string, required
  - `base_commit` string, required: The commit the conversation started from; empty for a home conversation.
  - `base_branch` string, nullable, required
  - `repo_remote` string, required
  - `home` boolean, required: A conversation on your machine’s home: no repository (`repo_remote`, `branch` and `base_commit` are empty). Its agent runs in `/home/user` on a computer from your machine environment and starts threads in the project’s repositories.
  - `state` 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived' | 'deleted', required: `deleted` only on the one feed delivery of a deleted conversation.
  - `changes` object, required
    - `files` integer, required
    - `insertions` integer, required
    - `deletions` integer, required
    - `commits` integer, required
    - `uncommitted` boolean, required
  - `landed` object, nullable, required
    - `how` 'merged' | 'pushed' | 'pr' | 'kept' | 'discarded' | 'no_changes', required
    - `at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `ref` string, required
  - `pending_move` object, nullable, required
    - `to` string, required
    - `requested_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `initial_input` object: Only a qualified computer guest receives its exact bound initial-input receipt metadata.
    - `protocol` 1, required
    - `input_id` string, required
    - `received` boolean, required
    - `recovery_blocked` boolean, required
    - `halted` boolean, required
    - `sha256` string, required
    - `bytes` integer, required
  - `brief` string, nullable, required
  - `last_activity_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `ended_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `model` string, nullable, required
  - `effort` string, nullable, required
  - `title_prefix` string, nullable: The marker the conversation’s Claude session title starts with; an empty string for none. Null: the default “☁ ”.
  - `started_by` object, nullable: The user who started the conversation: the signed-in user, or the user who created the API key that started it. A conversation a guest spawns, forks or joins carries its VM creator’s user. Null for conversations started before this was recorded and for a key without a known creator.
    - `user_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `question` string, nullable: Why the conversation needs you: the agent’s question or the reason its turn stopped (“Codex reached its usage limit; try again at 4:40 AM.”), on one line of up to 500 characters. Set while `state` is `needs_you`; null otherwise, and for a permission prompt that asks no question.
  - `title_short` string, nullable, required: The agent’s own short name for the conversation (“CSV export for todo list”): Claude Code’s generated title or the Codex thread name, on one line. Null until the agent has named it; show `title` meanwhile.
  - `updated_at` string, date-time, required: When something this conversation shows last changed (state, titles, summary, changes, landing, question, activity). GET /v1/conversations?updated_after= filters on it.
  - `deleted_at` string, date-time, nullable: Set once the conversation was deleted: a feed delivers it this one time, with its content cleared; remove it. Lists leave it out and it reads 404.
  - `parent_deleted` boolean: Its parent conversation was deleted (`parent_id` reads 404).
  - `needs_you_reason` 'permission' | 'question' | 'sign_in' | 'turn_failed', nullable: Why the conversation needs you, while `state` is `needs_you`: `permission` (the agent asks to use a tool), `question` (the agent asks you something), `sign_in` (the agent’s account must sign in again) or `turn_failed` (its turn stopped, for example on a usage limit; `question` says why). Null otherwise.
  - `seen_at` string, date-time, nullable: When you last opened this conversation, on any of your devices (POST /v1/conversations/marks `seen`). A conversation you never opened reads the time your marks start from (no earlier than when you joined its organization). A result is new to you when the conversation finished after this time. Each person has their own. Present on GET /v1/conversations, GET /v1/conversations/{id}, GET /v1/conversations/feed and POST /v1/conversations/marks; absent on other answers, which do not read marks.
  - `dismissed_at` string, date-time, nullable: When you archived this conversation from your inbox, on any of your devices (POST /v1/conversations/marks `dismissed`); null when you have not, or restored it. Each person has their own. Present where `seen_at` is.

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