CovenDocs
API ReferenceSessionsLaunch a session POST

Launch a session

1 min read

POST
/sessions

Request Body

application/json
  1. body
projectRoot*string

Absolute path to the project root. Will be canonicalized by the daemon.

cwd?string

Working directory for the harness. Must canonicalize inside projectRoot. Defaults to the project root when omitted.

harness*string

Supported harness id (codex or claude in coven.daemon.v1).

prompt*string

Task text passed to the harness as its final argv argument.

title?string

Readable session title for UI. Defaults to the prompt when omitted.

model?string

Optional namespaced model id (e.g. openai/gpt-5.6-sol). The harness adapter normalizes the provider prefix for the underlying CLI.

launchMode?string

How the harness process is driven. Defaults to interactive.

Value in"interactive""nonInteractive""stream"
conversation?|

Optional harness-native conversation hint. mode: init starts a new harness conversation with the given id; mode: resume resumes one. The id is forwarded verbatim to the harness CLI and is restricted to [A-Za-z0-9._-].

conversationId?string

Caller-supplied id used to group this session with other turns of the same chat conversation in /sessions. Independent of the harness CLI's own resume mechanism.

familiarId?string

Optional familiar id whose identity should be injected into the harness invocation. Unknown ids fail with 400 unknown_familiar.

writeScope?

Optional owner-local Claude scoped-write document. Requires harness claude and launchMode stream, cannot accompany launchPolicy, and is refused over TCP. Current execution qualification is macOS with Claude Code 2.1.318 or later and a functioning native sandbox. Confines shell/file-tool writes, not shell reads, networking, listed MCP tools, the per-user temporary directory or external actors. Roots must be existing absolute directories and obey the owning contract's overlap/alias rules. No fallback to unrestricted Full.

callerFamiliarId?string

Optional id of the familiar that spawned this session in a delegation; recorded in the Coven Calls ledger when set alongside familiarId.

Response Body

Session created and harness launched.

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' \  -H 'Content-Type: application/json' \  -d '{  "projectRoot": "/Users/example/project",  "cwd": "/Users/example/project",  "harness": "codex",  "prompt": "Fix the failing tests",  "title": "Fix failing tests"}'
{  "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