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

# Session API

> REST API endpoints for managing conversation sessions

The Session API provides endpoints for creating, managing, and querying conversation sessions in Goose.

## List Sessions

Get all available sessions.

```http theme={null}
GET /sessions
```

### Response

```json theme={null}
{
  "sessions": [
    {
      "id": "session-abc123",
      "name": "Code Review",
      "working_dir": "/home/user/project",
      "created_at": "2026-03-04T10:00:00Z",
      "updated_at": "2026-03-04T10:30:00Z",
      "input_tokens": 1500,
      "output_tokens": 800,
      "total_tokens": 2300
    }
  ]
}
```

### Example

```bash theme={null}
curl http://localhost:8080/sessions \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Get Session

Retrieve a specific session with full conversation history.

```http theme={null}
GET /sessions/{session_id}
```

### Response

```json theme={null}
{
  "id": "session-abc123",
  "name": "Code Review",
  "working_dir": "/home/user/project",
  "messages": [
    {
      "role": "user",
      "content": [{"type": "text", "text": "Review this code"}],
      "created_at": "2026-03-04T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": [{"type": "text", "text": "I'll review it..."}],
      "created_at": "2026-03-04T10:01:00Z"
    }
  ],
  "created_at": "2026-03-04T10:00:00Z",
  "updated_at": "2026-03-04T10:30:00Z"
}
```

### Example

```bash theme={null}
curl http://localhost:8080/sessions/session-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Search Sessions

Search sessions by keywords in conversation history.

```http theme={null}
GET /sessions/search
```

### Query Parameters

* `query` (required): Search keywords
* `limit` (optional): Max results (default: 10, max: 50)
* `after_date` (optional): ISO 8601 date filter
* `before_date` (optional): ISO 8601 date filter

### Response

```json theme={null}
[
  {
    "id": "session-abc123",
    "name": "Python debugging",
    "created_at": "2026-03-04T10:00:00Z"
  }
]
```

### Example

```bash theme={null}
curl "http://localhost:8080/sessions/search?query=python+error&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Update Session Name

Rename a session.

```http theme={null}
PUT /sessions/{session_id}/name
```

### Request Body

```json theme={null}
{
  "name": "Updated Session Name"
}
```

### Example

```bash theme={null}
curl -X PUT http://localhost:8080/sessions/session-abc123/name \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "My New Session Name"}'
```

## Delete Session

Permanently delete a session.

```http theme={null}
DELETE /sessions/{session_id}
```

### Example

```bash theme={null}
curl -X DELETE http://localhost:8080/sessions/session-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Export Session

Export session data as JSON for backup or transfer.

```http theme={null}
GET /sessions/{session_id}/export
```

### Response

Returns a JSON string containing the complete session data.

```json theme={null}
"{\"id\":\"session-abc123\",\"messages\":[...]}"
```

### Example

```bash theme={null}
curl http://localhost:8080/sessions/session-abc123/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  > session-backup.json
```

## Import Session

Import a previously exported session.

```http theme={null}
POST /sessions/import
```

### Request Body

```json theme={null}
{
  "json": "{\"id\":\"session-abc123\",\"messages\":[...]}"
}
```

### Response

Returns the imported `Session` object.

### Example

```bash theme={null}
curl -X POST http://localhost:8080/sessions/import \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"json": "..."}'
```

## Fork Session

Create a copy of a session or truncate conversation history.

```http theme={null}
POST /sessions/{session_id}/fork
```

### Request Body

```json theme={null}
{
  "timestamp": 1709550000000,
  "truncate": true,
  "copy": true
}
```

**Parameters:**

* `copy`: If `true`, creates a new session copy
* `truncate`: If `true`, removes messages after timestamp
* `timestamp`: Unix timestamp in milliseconds (required if `truncate` is `true`)

### Response

```json theme={null}
{
  "session_id": "session-xyz789"
}
```

### Examples

**Copy a session:**

```bash theme={null}
curl -X POST http://localhost:8080/sessions/session-abc123/fork \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"copy": true, "truncate": false}'
```

**Truncate conversation at a point in time:**

```bash theme={null}
curl -X POST http://localhost:8080/sessions/session-abc123/fork \
  -H "Content-Type: application/json" \
  -d '{
    "copy": false,
    "truncate": true,
    "timestamp": 1709550000000
  }'
```

## Get Session Extensions

Retrieve the extensions enabled for a specific session.

```http theme={null}
GET /sessions/{session_id}/extensions
```

### Response

```json theme={null}
{
  "extensions": [
    {
      "name": "filesystem",
      "type": "builtin",
      "description": "File system operations"
    },
    {
      "name": "developer",
      "type": "builtin",
      "description": "Development tools"
    }
  ]
}
```

### Example

```bash theme={null}
curl http://localhost:8080/sessions/session-abc123/extensions \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Update Recipe Values

Update user-provided recipe parameter values for a session.

```http theme={null}
PUT /sessions/{session_id}/user_recipe_values
```

### Request Body

```json theme={null}
{
  "user_recipe_values": {
    "target_language": "Python",
    "style": "concise"
  }
}
```

### Response

```json theme={null}
{
  "recipe": {
    "name": "code-helper",
    "instructions": "Help with Python code in a concise style"
  }
}
```

### Example

```bash theme={null}
curl -X PUT http://localhost:8080/sessions/session-abc123/user_recipe_values \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "user_recipe_values": {
      "language": "Rust"
    }
  }'
```

## Get Session Insights

Get aggregate statistics across all sessions.

```http theme={null}
GET /sessions/insights
```

### Response

```json theme={null}
{
  "total_sessions": 42,
  "total_messages": 1337,
  "total_tokens": 125000,
  "sessions_last_7_days": 8,
  "sessions_last_30_days": 28
}
```

### Example

```bash theme={null}
curl http://localhost:8080/sessions/insights \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Error Responses

| Code  | Description                      |
| ----- | -------------------------------- |
| `400` | Bad request - invalid parameters |
| `401` | Unauthorized - invalid API key   |
| `404` | Session not found                |
| `500` | Internal server error            |

### Error Format

```json theme={null}
{
  "message": "Session not found"
}
```

## Session Object Schema

A complete `Session` object has the following structure:

```json theme={null}
{
  "id": "string",
  "name": "string",
  "working_dir": "string",
  "created_at": "ISO 8601 timestamp",
  "updated_at": "ISO 8601 timestamp",
  "messages": [],
  "provider_name": "string",
  "model_config": {},
  "input_tokens": 0,
  "output_tokens": 0,
  "total_tokens": 0,
  "accumulated_input_tokens": 0,
  "accumulated_output_tokens": 0,
  "accumulated_total_tokens": 0,
  "recipe": {},
  "user_recipe_values": {},
  "extension_data": {}
}
```