CovenDocs

Complete an externally-registered session

1 min read

POST
/sessions/{id}/complete

Path Parameters

id*string

The session id (stable across daemon restarts).

Request Body

application/json
  1. body

Optional completion metadata. An empty or missing body marks the session completed.

exitCode?integer

Process exit code of the external session. Non-zero marks the session failed; zero (or omitted) marks it completed.

Response Body

The updated session record.

application/json
  1. response

The Rust daemon's SessionRecord shape. Field names use snake_case.

id*string
project_root*string

Absolute canonical project root path on this host.

harness*string

Harness id this session was launched with.

title*string

Human-readable session title.

status*SessionStatus

Session 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.
Value in"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.

Formatdate-time
created_at*string
Formatdate-time
updated_at*string
Formatdate-time
conversation_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*string

Session visibility. Defaults to private.

external*boolean

true 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}
Was this page helpful?No

Last updated on