Conversations

Get a conversation and current binding

get/v1/conversations/{id}

Request

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

Path parameters

idstring required

Response

Default Response

idstring required
project_idstring uuid required

UUIDv7, lowercase canonical form.

keystring required
namestring required
titlestring required
summarystring required
harness'claude' | 'codex' required
harness_session_idstring 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_idstring nullable
orchestrator_input_idstring 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_idstring nullable required
root_idstring required
workspace_idstring uuid required

UUIDv7, lowercase canonical form.

worktree_pathstring required
branchstring required
base_commitstring required

The commit the conversation started from; empty for a home conversation.

base_branchstring nullable required
repo_remotestring required
homeboolean 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.

briefstring nullable required
last_activity_atstring date-time required

RFC 3339 UTC timestamp with Z.

created_atstring date-time required

RFC 3339 UTC timestamp with Z.

ended_atstring date-time nullable required

RFC 3339 UTC timestamp with Z.

modelstring nullable required
effortstring nullable required
title_prefixstring nullable

The marker the conversation’s Claude session title starts with; an empty string for none. Null: the default “☁ ”.

questionstring 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_shortstring 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_atstring 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_atstring 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_deletedboolean

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

restoreobject nullable required
pty_idstring nullable required

The terminal the conversation’s harness runs in (terminal route), while its computer exists: attach to it through the cell’s PTY routes, with read_only to watch without typing. Null for other routes and ended conversations.

listening_ports_atstring date-time nullable required

When the guest last reported listening_ports.

Changes

No recorded changes to this operation across all 1 revision of this API.