Covendocs
API ReferenceSessionsLaunch a session POST
Report issue

Launch a session

Launch a new harness session under an enforced project root.

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"
}

{
  "error": {
    "code": "project_root_violation",
    "message": "cwd must canonicalize inside project root.",
    "details": {
      "projectRoot": "/Users/example/project",
      "cwd": "/tmp/somewhere-else"
    }
  }
}

{
  "error": {
    "code": "pty_spawn_failed",
    "message": "Could not spawn harness PTY.",
    "details": {
      "harness": "codex",
      "cause": "ENOENT"
    }
  }
}
{
  "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