CovenDocs

Register an externally-launched session

1 min read

POST
/sessions/external

Request Body

application/json
  1. body
id*string

Caller-chosen session id. Registration is idempotent on this id.

projectRoot*string

Absolute project root path the external session ran in.

harness*string

Harness id the external session used.

title?string

Readable session title. Defaults to External session when omitted or blank.

transcriptPath?string

Absolute path to the transcript file written by the external session.

Response Body

A session with this id was already registered; the persisted record is returned.

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/external' \  -H 'Content-Type: application/json' \  -d '{  "id": "engine-session-1",  "projectRoot": "/Users/example/project",  "harness": "codex",  "title": "Engine TUI run",  "transcriptPath": "/Users/example/.coven/transcripts/engine-session-1.jsonl"}'
{  "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