Sessions API

Create and manage coding sessions

Sessions represent coding work periods. Each session groups related observations.

Create Session

POST /sessions

Create a new session or update an existing one.

Request Body

id · string · required

Unique session identifier. Use UUIDs or timestamps for uniqueness.

project · string · required

Project name (e.g., “engram”, “my-app”)

directory · string

Working directory path

Response

id · string

The session ID

status · string

Always “created”

Example

curl -X POST http://127.0.0.1:7437/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "id": "session-abc123",
    "project": "engram",
    "directory": "/home/user/projects/engram"
  }'

{
  "id": "session-abc123",
  "status": "created"
}

End Session

POST /sessions/{id}/end

Mark a session as completed with an optional summary.

Path Parameters

id · string · required

Session ID to end

Request Body

summary · string

Optional session summary describing what was accomplished

Response

id · string

The session ID

status · string

Always “completed”

Example

curl -X POST http://127.0.0.1:7437/sessions/session-abc123/end \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Implemented user authentication and fixed login bug"
  }'

{
  "id": "session-abc123",
  "status": "completed"
}

Get Recent Sessions

GET /sessions/recent

Retrieve recent sessions, optionally filtered by project.

Query Parameters

project · string

Filter by project name

limit · integer · default: "5"

Maximum number of sessions to return (1-100)

Response

Returns an array of session summaries:

id · string

Session ID

project · string

Project name

started_at · string

ISO 8601 timestamp when session started

ended_at · string | null

ISO 8601 timestamp when session ended (null if still active)

summary · string | null

Session summary if provided

observation_count · integer

Number of observations in this session

Example

curl "http://127.0.0.1:7437/sessions/recent?project=engram&limit=3"

[
  {
    "id": "session-abc123",
    "project": "engram",
    "started_at": "2024-03-15 14:30:00",
    "ended_at": "2024-03-15 16:45:00",
    "summary": "Implemented user authentication",
    "observation_count": 12
  },
  {
    "id": "session-def456",
    "project": "engram",
    "started_at": "2024-03-14 10:00:00",
    "ended_at": null,
    "summary": null,
    "observation_count": 5
  }
]

Session Schema

Complete session object structure:

interface Session {
  id: string;
  project: string;
  directory: string;
  started_at: string;  // ISO 8601
  ended_at?: string | null;  // ISO 8601
  summary?: string | null;
}

interface SessionSummary {
  id: string;
  project: string;
  started_at: string;
  ended_at?: string | null;
  summary?: string | null;
  observation_count: number;
}