Skip to main content

​
Overview

Sessions track active coding agent conversations in a workspace. They’re created and managed automatically by IDE hooks — you don’t typically call these endpoints directly.

​
Hook Endpoint

The primary endpoint. Handles all IDE hook events. 
POST /workspaces/sessions/hook
Authorization: Bearer ek_...

{
  "event": "sessionStart",
  "agent_type": "cursor",
  "workspace_slug": "my-startup",
  "conversation_id": "conv_abc123",
  "task": "Build user authentication"
}

​
Event Types

EventIDEEffect
sessionStart / SessionStartCursor / Claude Code, CodexCreates session, returns context briefing
preToolUse / PreToolUseCursor / Claude CodeChecks file reservation, may deny write
postToolUse / PostToolUseCursor / Claude CodeReserves file for this conversation
beforeSubmitPrompt / UserPromptSubmitCursor / Claude Code, CodexCaptures task text
sessionEnd / SessionEnd / StopCursor / Claude Code, CodexReleases reservations, ends session
file_checkAnyUpdates heartbeat

​
sessionStart Response

{
  "session_id": "sess_xyz",
  "additional_context": "Team briefing:\n\nActive agents:\n  - Developer B (Cursor): Build JWT auth flow\n\nLocked files:\n  - src/auth/login.ts (Developer B)\n\nRecent decisions:\n  - Use JWT for auth (Developer B, 5 min ago)"
}
The additional_context field is injected as system context by the IDE.

​
preToolUse Response (deny)

{
  "permission": "deny",
  "message": "File src/auth/login.ts is reserved by Developer B — 'Build JWT auth flow' (6 min remaining)"
}

​
preToolUse Response (allow)

{
  "permission": "allow"
}

​
List Active Sessions

GET /workspaces/:id/sessions
Authorization: Bearer ek_...
Response 
[
  {
    "id": "sess_abc",
    "user_name": "Developer A",
    "agent_type": "cursor",
    "current_task": "Build JWT auth flow",
    "current_file": "src/auth/login.ts",
    "branch": "feat/auth",
    "conversation_id": "conv_xyz",
    "last_heartbeat": "2026-04-13T10:30:00Z",
    "reserved_files": ["src/auth/login.ts", "src/auth/middleware.ts"]
  }
]

​
Heartbeat

Keep a session alive. 
POST /workspaces/sessions/heartbeat
Authorization: Bearer ek_...

{
  "workspace_slug": "my-startup",
  "session_id": "sess_abc"
}

​
End Session

POST /workspaces/sessions/end
Authorization: Bearer ek_...

{
  "workspace_slug": "my-startup",
  "session_id": "sess_abc"
}
Releases all file reservations for the session.

​
Session Expiry

Sessions auto-expire after 5 minutes of inactivity (no hook events). File reservations auto-expire after 10 minutes of inactivity.