Covendocs
API ReferenceSessionsLaunch a session POST
Report issue

Launch a session

1 min read

POST
/sessions

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" \  -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: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": "project_root_violation",
    "message": "cwd must canonicalize inside project root.",
    "details": {
      "projectRoot": "/Users/example/project",
      "cwd": "/tmp/somewhere-else"
    }
  }
}

{
  "error": {
    "code": "launch_failed",
    "message": "Could not launch harness session.",
    "details": {
      "sessionId": "session-1"
    }
  }
}
{
  "error": {
    "code": "runtime_unavailable",
    "message": "Session runtime is unavailable.",
    "details": {}
  }
}
{
  "error": {
    "code": "internal_error",
    "message": "Unexpected internal daemon error.",
    "details": {}
  }
}
Was this page helpful?No