> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField body="id" type="string" required>
  Unique session identifier. Use UUIDs or timestamps for uniqueness.
</ParamField>

<ParamField body="project" type="string" required>
  Project name (e.g., "engram", "my-app")
</ParamField>

<ParamField body="directory" type="string">
  Working directory path
</ParamField>

### Response

<ResponseField name="id" type="string">
  The session ID
</ResponseField>

<ResponseField name="status" type="string">
  Always "created"
</ResponseField>

### Example

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "id": "session-abc123",
  "status": "created"
}
```

## End Session

`POST /sessions/{id}/end`

Mark a session as completed with an optional summary.

### Path Parameters

<ParamField path="id" type="string" required>
  Session ID to end
</ParamField>

### Request Body

<ParamField body="summary" type="string">
  Optional session summary describing what was accomplished
</ParamField>

### Response

<ResponseField name="id" type="string">
  The session ID
</ResponseField>

<ResponseField name="status" type="string">
  Always "completed"
</ResponseField>

### Example

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "id": "session-abc123",
  "status": "completed"
}
```

## Get Recent Sessions

`GET /sessions/recent`

Retrieve recent sessions, optionally filtered by project.

### Query Parameters

<ParamField query="project" type="string">
  Filter by project name
</ParamField>

<ParamField query="limit" type="integer" default="5">
  Maximum number of sessions to return (1-100)
</ParamField>

### Response

Returns an array of session summaries:

<ResponseField name="id" type="string">
  Session ID
</ResponseField>

<ResponseField name="project" type="string">
  Project name
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 timestamp when session started
</ResponseField>

<ResponseField name="ended_at" type="string | null">
  ISO 8601 timestamp when session ended (null if still active)
</ResponseField>

<ResponseField name="summary" type="string | null">
  Session summary if provided
</ResponseField>

<ResponseField name="observation_count" type="integer">
  Number of observations in this session
</ResponseField>

### Example

```bash theme={null}
curl "http://127.0.0.1:7437/sessions/recent?project=engram&limit=3"
```

```json theme={null}
[
  {
    "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:

```typescript theme={null}
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;
}
```