REST API

The Claude Session Tools server exposes a REST API for session management.

Base URL

http://localhost:3000/api

Endpoints

List Sessions

Retrieve all monitored sessions.

GET /api/sessions

Response

{
  "sessions": [
    {
      "name": "my-project",
      "claude": {
        "primary": "active",
        "detail": "thinking",
        "health": "ALIVE",
        "timestamp": "2024-01-15T10:30:00.000Z",
        "unchangedCount": 0
      }
    }
  ]
}

Response Fields

Field	Type	Description
sessions	array	List of session objects
sessions[].name	string	Session identifier
sessions[].claude	object	Claude status information
sessions[].claude.primary	string	Primary status
sessions[].claude.detail	string	Detail status (nullable)
sessions[].claude.health	string	Health state
sessions[].claude.timestamp	string	ISO 8601 timestamp
sessions[].claude.unchangedCount	number	Consecutive unchanged checks

---

Create Session

Add a session to monitoring.

POST /api/sessions

Request Body

{
  "name": "my-project"
}

Request Fields

Field	Type	Required	Description
name	string	Yes	Session name (must match loggable-session name)

Response (Success)

{
  "success": true,
  "session": {
    "name": "my-project",
    "claude": {
      "primary": "idle",
      "detail": "waiting_input",
      "health": "ALIVE",
      "timestamp": "2024-01-15T10:30:00.000Z",
      "unchangedCount": 0
    }
  }
}

Response (Error)

{
  "success": false,
  "error": "Session not found"
}

Status Codes

Code	Description
200	Session created and monitoring started
400	Invalid request (missing name)
404	Session not found in loggable-session
409	Session already being monitored

---

Delete Session

Remove a session from monitoring.

DELETE /api/sessions/:name

Path Parameters

Parameter	Type	Description
name	string	Session name to remove

Response (Success)

{
  "success": true
}

Response (Error)

{
  "success": false,
  "error": "Session not found"
}

Status Codes

Code	Description
200	Session removed from monitoring
404	Session not being monitored

---

Error Handling

All error responses follow this format:

{
  "success": false,
  "error": "Error message description"
}

Common error scenarios:

Error	Cause	Resolution
Session not found	Session name does not exist in loggable-session	Verify session is running with logsession list
Session already monitored	Attempting to add duplicate session	Session is already being tracked
Invalid session name	Empty or malformed name	Provide valid session identifier

Usage Examples

cURL

List sessions:

curl http://localhost:3000/api/sessions

Create session:

curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project"}'

Delete session:

curl -X DELETE http://localhost:3000/api/sessions/my-project

JavaScript (fetch)

// List sessions
const response = await fetch('http://localhost:3000/api/sessions');
const data = await response.json();

// Create session
await fetch('http://localhost:3000/api/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'my-project' })
});

// Delete session
await fetch('http://localhost:3000/api/sessions/my-project', {
  method: 'DELETE'
});

Rate Limiting

The API does not currently implement rate limiting. For production deployments with many clients, consider adding rate limiting middleware.

Authentication

The API does not currently implement authentication. For production deployments, consider:

• Adding API key authentication
• Implementing JWT tokens
• Using reverse proxy authentication