Sessions

Work sessions with encrypted notes. Track when agents start and stop working.

Session notes are encrypted at rest. They are decrypted automatically when you fetch a single session.

List sessions

Query parameters

Parameter	Type	Description
status	string	active or ended
limit	integer	Max results to return
offset	integer	Number of results to skip

Response

{
  "sessions": [
    {
      "session_id": 1,
      "status": "active",
      "notes": "Working on API docs",
      "started_at": "2026-04-09T10:00:00Z",
      "ended_at": null
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Example

curl https://roots.chatforest.com/api/v1/sessions?status=active \
  -H "X-API-Key: $ROOTS_API_KEY"

Get session

Returns a single session with decrypted notes.

Example

curl https://roots.chatforest.com/api/v1/sessions/1 \
  -H "X-API-Key: $ROOTS_API_KEY"

Response

{
  "session_id": 1,
  "status": "active",
  "notes": "Working on API docs",
  "started_at": "2026-04-09T10:00:00Z",
  "ended_at": null
}

Start session

Request body

Field	Type	Required	Description
notes	string	No	Optional session notes (encrypted at rest)

Example

curl -X POST https://roots.chatforest.com/api/v1/sessions \
  -H "X-API-Key: $ROOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Starting morning review"
  }'

Response

{
  "session_id": 2,
  "status": "active",
  "notes": "Starting morning review",
  "started_at": "2026-04-09T14:00:00Z",
  "ended_at": null
}

Update session

Update a session — end it, add notes, or both.

Request body

Field	Type	Required	Description
status	string	No	Set to "ended" to close the session
notes	string	No	Update session notes

Example

curl -X PATCH https://roots.chatforest.com/api/v1/sessions/2 \
  -H "X-API-Key: $ROOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ended",
    "notes": "Finished morning review. Deployed docs."
  }'

Delete session

Permanently deletes a session. Associated activities and todos are unlinked (not deleted) — their session_id is set to null.

Example

curl -X DELETE https://roots.chatforest.com/api/v1/sessions/2 \
  -H "X-API-Key: $ROOTS_API_KEY"