Get Recent Sessions

Retrieve the most recent sessions across all projects

GET /api/v1/sessions/recent

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cloud.specstory.com/api/v1/sessions/recent?limit=10"

200 Success

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "projectId": "proj_abc123",
        "name": "Feature Implementation",
        "markdownSize": 22340,
        "rawDataSize": 45678,
        "createdAt": "2024-01-20T16:30:00.000Z",
        "updatedAt": "2024-01-20T18:45:30.000Z",
        "startedAt": "2024-01-20T16:30:00.000Z",
        "endedAt": "2024-01-20T18:45:30.000Z",
        "metadata": {
          "clientName": "VSCode",
          "clientVersion": "1.85.0",
          "agentName": "SpecStory Agent",
          "deviceId": "device456",
          "gitBranches": ["feature-branch"],
          "llmModels": ["claude-3-sonnet"],
          "tags": ["feature", "api"]
        }
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "projectId": "proj_def456",
        "name": "Debug Session",
        "markdownSize": 8765,
        "rawDataSize": 15432,
        "createdAt": "2024-01-20T14:00:00.000Z",
        "updatedAt": "2024-01-20T15:30:00.000Z",
        "startedAt": "2024-01-20T14:00:00.000Z",
        "endedAt": "2024-01-20T15:30:00.000Z",
        "metadata": {
          "clientName": "Cursor",
          "clientVersion": "2.0.0",
          "agentName": "Debug Agent",
          "deviceId": "device789",
          "gitBranches": ["debug-fix"],
          "llmModels": ["gpt-4"],
          "tags": ["debugging"]
        }
      }
    ],
    "total": 2
  }
}

Request

limit · integer · default: 5

Number of sessions to return (1-100)

Authorization · string · required

Bearer token for authentication

Response

success · boolean

Indicates if the request was successful

data · object

Show data

sessions · array

Array of recent session objects

Show 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

Show 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

total · number

Total number of sessions returned

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cloud.specstory.com/api/v1/sessions/recent?limit=10"

200 Success

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "projectId": "proj_abc123",
        "name": "Feature Implementation",
        "markdownSize": 22340,
        "rawDataSize": 45678,
        "createdAt": "2024-01-20T16:30:00.000Z",
        "updatedAt": "2024-01-20T18:45:30.000Z",
        "startedAt": "2024-01-20T16:30:00.000Z",
        "endedAt": "2024-01-20T18:45:30.000Z",
        "metadata": {
          "clientName": "VSCode",
          "clientVersion": "1.85.0",
          "agentName": "SpecStory Agent",
          "deviceId": "device456",
          "gitBranches": ["feature-branch"],
          "llmModels": ["claude-3-sonnet"],
          "tags": ["feature", "api"]
        }
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "projectId": "proj_def456",
        "name": "Debug Session",
        "markdownSize": 8765,
        "rawDataSize": 15432,
        "createdAt": "2024-01-20T14:00:00.000Z",
        "updatedAt": "2024-01-20T15:30:00.000Z",
        "startedAt": "2024-01-20T14:00:00.000Z",
        "endedAt": "2024-01-20T15:30:00.000Z",
        "metadata": {
          "clientName": "Cursor",
          "clientVersion": "2.0.0",
          "agentName": "Debug Agent",
          "deviceId": "device789",
          "gitBranches": ["debug-fix"],
          "llmModels": ["gpt-4"],
          "tags": ["debugging"]
        }
      }
    ],
    "total": 2
  }
}