CLI Sessions API

RESTful API for managing CLI sessions, including creation, lifecycle management, and memory tracking.

Updated Oct 6, 2026

Overview

The CLI Sessions API provides endpoints for creating, managing, and tracking work sessions. Sessions organize memories into contextual groups with lifecycle management (active, paused, completed).

Base URL: https://api.trixdb.com/v1

Authentication: All endpoints require a valid API key or session token in the Authorization header.

Create Session

Endpoint

POST /cli-sessions

Creates a new CLI session with the specified configuration. The session is created in active status by default.

Body Parameters

Field	Type	Description
name	string (required)	Name of the session. Maximum 200 characters. Should be descriptive and unique.
type	string	Session type: `conversation`, `project`, `task`, or `temporary`. Default: `conversation`
description	string	Detailed description of the session. Maximum 1000 characters.
space_id	string	Associate session with a specific space.
origin_type	string	Source of the session (e.g., "cli", "api", "zendesk"). Used for tracking and analytics.
tags	array	Array of strings for organizing sessions. Maximum 10 tags, each up to 50 characters.
retention_policy	string	Retention policy: `permanent`, `temporary`, `auto_delete`, or `on_completion`. Default: `permanent`
retention_days	integer	Number of days before auto-deletion (required when `retention_policy` is `auto_delete`).
is_private	boolean	Whether the session is private. Private sessions are only visible to the creator and account admins. Default: `false`
metadata	object	Optional key-value pairs for custom metadata.

Response (201)

Returns the created session object with generated ID and timestamps.

Example Response

{
  "id": "<uuid>",
  "account_id": "<account-uuid>",
  "created_by": "<api-key-uuid>",
  "name": "Q4 Marketing Campaign",
  "type": "project",
  "status": "active",
  "description": "Social media and email campaigns for Q4 2024",
  "tags": ["marketing", "q4", "campaigns"],
  "space_id": "<space-uuid>",
  "retention_policy": "permanent",
  "is_private": false,
  "message_count": 0,
  "memory_count": 0,
  "metadata": {},
  "created_at": "2026-04-10T10:30:00Z",
  "updated_at": "2026-04-10T10:30:00Z",
  "last_active_at": "2026-04-10T10:30:00Z"
}

List Sessions

Endpoint

GET /cli-sessions

Returns a paginated list of sessions with optional filtering. Supports filtering by status, type, space, tags, and search query.

Query Parameters

Field	Type	Description
status	string	Filter by status: `active`, `paused`, `completed`, or `archived`
type	string	Filter by type: `conversation`, `project`, `task`, or `temporary`
space_id	string	Filter by space ID
origin_type	string	Filter by origin type
tags	string	Comma-separated list of tags. Returns sessions matching any tag.
search	string	Search in session name and description
include_archived	boolean	Include archived sessions. Default: `false`
sort	string	Sort field: `created_at`, `updated_at`, `last_active_at`, or `name`. Default: `created_at`
order	string	Sort order: `asc` or `desc`. Default: `desc`
limit	integer	Maximum results per page. Default: 20, Max: 100
offset	integer	Number of results to skip for pagination

Response (200)

Example Response

{
  "data": [
    {
      "id": "<uuid>",
      "name": "Q4 Marketing Campaign",
      "type": "project",
      "status": "active",
      "description": "Social media and email campaigns",
      "tags": ["marketing", "q4"],
      "memory_count": 24,
      "message_count": 156,
      "created_at": "2026-04-10T10:30:00Z",
      "last_active_at": "2026-04-14T14:22:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Get Active Sessions

Endpoint

GET /cli-sessions/active

Returns a list of currently active sessions, sorted by most recently active.

Query Parameters

Field	Type	Description
limit	integer	Maximum number of sessions to return. Default: 20.

Response (200)

Example Response

{
  "data": [
    {
      "id": "<uuid>",
      "name": "Q4 Marketing Campaign",
      "type": "project",
      "status": "active",
      "memory_count": 24,
      "last_active_at": "2026-04-14T14:22:00Z"
    }
  ],
  "count": 3
}

Get Session Statistics

Endpoint

GET /cli-sessions/stats

Returns aggregate statistics about sessions in the account.

Response (200)

Example Response

{
  "total": 127,
  "by_status": {
    "active": 12,
    "paused": 5,
    "completed": 98,
    "archived": 12
  },
  "by_type": {
    "conversation": 45,
    "project": 38,
    "task": 32,
    "temporary": 12
  }
}

Get Session

Endpoint

GET /cli-sessions/:id

Retrieves a single session with complete details including memory counts and lifecycle timestamps.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the session

Response (200)

Example Response

{
  "id": "<uuid>",
  "account_id": "<account-uuid>",
  "created_by": "<api-key-uuid>",
  "name": "Q4 Marketing Campaign",
  "type": "project",
  "status": "active",
  "description": "Social media and email campaigns for Q4 2024",
  "tags": ["marketing", "q4", "campaigns"],
  "space_id": "<space-uuid>",
  "origin_type": "cli",
  "retention_policy": "permanent",
  "is_private": false,
  "message_count": 156,
  "memory_count": 24,
  "metadata": {},
  "created_at": "2026-04-10T10:30:00Z",
  "updated_at": "2026-04-14T14:22:00Z",
  "last_active_at": "2026-04-14T14:22:00Z",
  "paused_at": null,
  "completed_at": null,
  "archived_at": null
}

Update Session

Endpoint

PATCH /cli-sessions/:id

Updates session name, description, tags, retention policy, or privacy settings. Only provided fields are updated.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the session to update

Body Parameters

Field	Type	Description
name	string	Updated session name
description	string	Updated description
tags	array	Updated tags array (replaces existing tags)
retention_policy	string	Updated retention policy
retention_days	integer	Updated retention days
is_private	boolean	Updated privacy setting
metadata	object	Updated metadata (merges with existing)
summary	string	Session summary (typically added when completing)

Response (200)

Example Response

{
  "id": "<uuid>",
  "name": "Q4 Marketing Campaign",
  "description": "Updated description with more details",
  "tags": ["marketing", "q4", "campaigns", "high-priority"],
  "updated_at": "2026-04-14T15:30:00Z"
}

Delete Session

Endpoint

DELETE /cli-sessions/:id

Permanently deletes a session and all associated memories. This action cannot be undone.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the session to delete

Response (204)

Returns empty response on successful deletion.

Deleting a session permanently removes it and all associated memories. Consider completing or archiving the session instead.

Pause Session

Endpoint

POST /cli-sessions/:id/pause

Pauses an active session, preventing new memories from being added. The session can be resumed later.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the session to pause

Response (200)

Example Response

{
  "id": "<uuid>",
  "name": "Q4 Marketing Campaign",
  "status": "paused",
  "paused_at": "2026-04-14T16:00:00Z",
  "updated_at": "2026-04-14T16:00:00Z"
}

Only active sessions can be paused. Attempting to pause a completed or archived session will return an error.

Resume Session

Endpoint

POST /cli-sessions/:id/resume

Resumes a paused session, allowing new memories to be added again.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the session to resume

Response (200)

Example Response

{
  "id": "<uuid>",
  "name": "Q4 Marketing Campaign",
  "status": "active",
  "paused_at": null,
  "updated_at": "2026-04-14T17:00:00Z",
  "last_active_at": "2026-04-14T17:00:00Z"
}

Only paused sessions can be resumed. Completed or archived sessions cannot be reopened.

Complete Session

Endpoint

POST /cli-sessions/:id/complete

Marks a session as completed with an optional summary. Completed sessions are read-only.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the session to complete

Body Parameters

Field	Type	Description
summary	string	Optional summary describing the outcome or completion notes. Maximum 2000 characters.

Response (200)

Example Response

{
  "id": "<uuid>",
  "name": "Q4 Marketing Campaign",
  "status": "completed",
  "summary": "Successfully launched all Q4 campaigns with 15% increase in engagement",
  "completed_at": "2026-04-14T18:00:00Z",
  "updated_at": "2026-04-14T18:00:00Z"
}

Get Session Memories

Endpoint

GET /cli-sessions/:id/memories

Returns all memories associated with a specific session, with pagination support.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the session

Query Parameters

Field	Type	Description
limit	integer	Maximum results per page. Default: 20, Max: 100
offset	integer	Number of results to skip for pagination

Response (200)

Example Response

{
  "data": [
    {
      "id": "<uuid>",
      "content": "Launched Facebook campaign targeting age 25-40",
      "session_id": "<uuid>",
      "created_at": "2026-04-11T10:00:00Z"
    },
    {
      "id": "<uuid>",
      "content": "Email campaign achieved 24% open rate",
      "session_id": "<uuid>",
      "created_at": "2026-04-12T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 24,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Error Responses

The API returns standard HTTP status codes and JSON error responses:

Status Code	Error	Description
`400`	Bad Request	Invalid parameters or malformed request body
`401`	Unauthorized	Missing or invalid authentication credentials
`403`	Forbidden	Insufficient permissions to access this session
`404`	Not Found	Session not found or has been deleted
`409`	Conflict	Invalid state transition (e.g., resume a non-paused session)
`422`	Validation Error	Request validation failed (e.g., name too long)
`500`	Internal Server Error	Unexpected server error occurred

Error Response Format

Example Error Response

{
  "error": {
    "code": "invalid_state_transition",
    "message": "Cannot pause a completed session",
    "details": {
      "current_status": "completed",
      "requested_action": "pause"
    }
  }
}

Next Steps

Sessions Guide - Conceptual overview and workflows
CLI Sessions - Command-line interface
Memories API - Creating session-scoped memories
Authentication - API key and token management