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.

GET /sessions

Response

{
  "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

curl http://localhost:8080/sessions \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Session

Retrieve a specific session with full conversation history.

GET /sessions/{session_id}

Response

{
  "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

curl http://localhost:8080/sessions/session-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Search Sessions

Search sessions by keywords in conversation history.

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

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

Example

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

Update Session Name

Rename a session.

PUT /sessions/{session_id}/name

Request Body

{
  "name": "Updated Session Name"
}

Example

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.

DELETE /sessions/{session_id}

Example

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.

GET /sessions/{session_id}/export

Response

Returns a JSON string containing the complete session data.

"{\"id\":\"session-abc123\",\"messages\":[...]}"

Example

curl http://localhost:8080/sessions/session-abc123/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  > session-backup.json

Import Session

Import a previously exported session.

POST /sessions/import

Request Body

{
  "json": "{\"id\":\"session-abc123\",\"messages\":[...]}"
}

Response

Returns the imported Session object.

Example

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.

POST /sessions/{session_id}/fork

Request Body

{
  "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

{
  "session_id": "session-xyz789"
}

Examples

Copy a session:

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:

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.

GET /sessions/{session_id}/extensions

Response

{
  "extensions": [
    {
      "name": "filesystem",
      "type": "builtin",
      "description": "File system operations"
    },
    {
      "name": "developer",
      "type": "builtin",
      "description": "Development tools"
    }
  ]
}

Example

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.

PUT /sessions/{session_id}/user_recipe_values

Request Body

{
  "user_recipe_values": {
    "target_language": "Python",
    "style": "concise"
  }
}

Response

{
  "recipe": {
    "name": "code-helper",
    "instructions": "Help with Python code in a concise style"
  }
}

Example

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.

GET /sessions/insights

Response

{
  "total_sessions": 42,
  "total_messages": 1337,
  "total_tokens": 125000,
  "sessions_last_7_days": 8,
  "sessions_last_30_days": 28
}

Example

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

{
  "message": "Session not found"
}

Session Object Schema

A complete Session object has the following structure:

{
  "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": {}
}