Complete an externally-registered session
1 min read
id*stringThe session id (stable across daemon restarts).
application/json- body
Optional completion metadata. An empty or missing body marks the session completed.
exitCode?integerProcess exit code of the external session. Non-zero marks the session failed; zero (or omitted) marks it completed.
The updated session record.
application/json- response
The Rust daemon's SessionRecord shape. Field names use snake_case.
id*stringproject_root*stringAbsolute canonical project root path on this host.
harness*stringHarness id this session was launched with.
title*stringHuman-readable session title.
status*SessionStatusSession lifecycle state machine values:
created: record exists, harness not yet running.running: harness PTY is active.completed: harness exited with code 0.failed: setup or non-zero exit.killed: live kill request was accepted.orphaned: previous daemon stopped while running.
"created""running""completed""failed""killed""orphaned"exit_code*|Process exit code if the harness exited; null while running or not yet exited.
archived_at*|ISO-8601 timestamp of archival, or null if active.
date-timecreated_at*stringdate-timeupdated_at*stringdate-timeconversation_id*|Optional grouping id so multi-turn chat conversations show as one
thread in /sessions instead of one row per turn. null for
ungrouped one-off runs.
familiar_id*|Familiar id this session was launched with (e.g. via
coven run --familiar <id>). null for direct launches without
the flag and for legacy sessions.
labels*array<string>Client-facing labels attached to this session. Empty when unlabeled.
visibility*stringSession visibility. Defaults to private.
external*booleantrue when the session was launched outside the daemon (e.g. by
the coven engine TUI) and registered via POST /sessions/external.
The daemon does not own the PTY for external sessions; it only
holds the ledger row.
transcript_path*|Absolute path to the transcript file written by an external
session. Only meaningful when external is true.
curl -X POST 'http://localhost:3000/api/v1/sessions/session-1/complete' \ -H 'Content-Type: application/json' \ -d '{ "exitCode": 0}'{ "id": "session-1", "project_root": "/Users/example/project", "harness": "codex", "title": "Fix failing tests", "status": "running", "exit_code": null, "archived_at": null, "created_at": "2026-05-09T06:43:00Z", "updated_at": "2026-05-09T06:43:05Z", "conversation_id": null, "familiar_id": null, "labels": [], "visibility": "private", "external": false, "transcript_path": null}Last updated on