Skip to content
docs
Menu
#

List Sessions

List all sessions for a specific project

GET /api/v1/projects/{projectId}/sessions
On this page
#

Request

projectId string · path · required

The unique identifier of the project

Authorization string · header · required

Bearer token for authentication

#

Response

success boolean

Indicates if the request was successful

data object

data

sessions array

Array of session objects

session

id string

Unique session identifier (UUID format)

projectId string

Associated project ID

name string

Session name

markdownSize number

Size of markdown content in bytes

rawDataSize number

Size of raw data in bytes

createdAt string

ISO 8601 creation timestamp

updatedAt string

ISO 8601 last update timestamp

startedAt string

ISO 8601 timestamp when session started

endedAt string

ISO 8601 timestamp when session ended

metadata object

metadata

clientName string

Name of the client application

clientVersion string

Version of the client application

agentName string

Name of the agent

deviceId string

Unique device identifier

gitBranches array

Array of git branches

llmModels array

Array of LLM models used

tags array

Array of session tags

etag string

ETag for caching

total number

Total number of sessions

projectId string

Project ID for reference

#

Request examples

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://cloud.specstory.com/api/v1/projects/proj_abc123/sessions

JavaScript

const response = await fetch('https://cloud.specstory.com/api/v1/projects/proj_abc123/sessions', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();

Python

import requests

response = requests.get(
    'https://cloud.specstory.com/api/v1/projects/proj_abc123/sessions',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

data = response.json()
#

Response examples

200 Success

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "projectId": "proj_abc123",
        "name": "Bug Fix Discussion",
        "markdownSize": 15420,
        "rawDataSize": 28956,
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T14:45:30.000Z",
        "startedAt": "2024-01-15T10:30:00.000Z",
        "endedAt": "2024-01-15T14:45:30.000Z",
        "metadata": {
          "clientName": "Cursor",
          "clientVersion": "1.0.0",
          "agentName": "Test Agent",
          "deviceId": "device123",
          "gitBranches": ["main"],
          "llmModels": ["claude-3-opus", "gpt-4"],
          "tags": ["bug-fix", "authentication"]
        },
        "etag": "W/\"3bf2-18d4c5a8f90\""
      }
    ],
    "total": 1,
    "projectId": "proj_abc123"
  }
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid or missing authentication token"
}