Skip to main content
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

CodeDescription
400Bad request - invalid parameters
401Unauthorized - invalid API key
404Session not found
500Internal 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": {}
}

Build docs developers (and LLMs) love

Get started for freeTalk to us