Covendocs
API ReferenceSessionsRegister an externally-launched session POST
Report issue

Register an externally-launched session

1 min read

POST
/sessions/external

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/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:00.000Z",
  "updated_at": "2026-05-09T06:43:05.000Z",
  "conversation_id": null,
  "familiar_id": null,
  "labels": [],
  "visibility": "private",
  "external": false,
  "transcript_path": null
}
{
  "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:00.000Z",
  "updated_at": "2026-05-09T06:43:05.000Z",
  "conversation_id": null,
  "familiar_id": null,
  "labels": [],
  "visibility": "private",
  "external": false,
  "transcript_path": null
}
{
  "error": {
    "code": "invalid_request",
    "message": "Required field \"sessionId\" is missing.",
    "details": {
      "field": "sessionId"
    }
  }
}
{
  "error": {
    "code": "session_id_conflict",
    "message": "A daemon-managed session with this id already exists.",
    "details": {
      "sessionId": "session-1"
    }
  }
}
{
  "error": {
    "code": "internal_error",
    "message": "Unexpected internal daemon error.",
    "details": {}
  }
}
Was this page helpful?No