Skip to content
docs
Menu
#

Get Session

Retrieve a specific session with its content and metadata

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

Request

projectId string · path · required

The unique identifier of the project

sessionId string · path · required

The unique identifier of the session

Authorization string · header · required

Bearer token for authentication

Accept string · header

Content type for response. Options:

  • application/json (default) - Returns structured JSON
  • text/markdown - Returns raw markdown content

If-None-Match string · header

ETag value for conditional requests

#

Response

success boolean

Indicates if the request was successful

data object

data

session object

session

id string

Unique session identifier

name string

Session name

markdownContent string

Full markdown content of the session

markdownSize number

Size of markdown content in bytes

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

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

project object

project

id string

Project ID

name string

Project name

icon string

Project icon

color string

Project color

#

Request examples

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  https://cloud.specstory.com/api/v1/projects/proj_abc123/sessions/550e8400-e29b-41d4-a716-446655440000

JavaScript

const response = await fetch(
  'https://cloud.specstory.com/api/v1/projects/proj_abc123/sessions/550e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json'
    }
  }
);

const data = await response.json();

Python

import requests

response = requests.get(
    'https://cloud.specstory.com/api/v1/projects/proj_abc123/sessions/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json'
    }
)

data = response.json()
#

Response examples

200 Success

{
  "success": true,
  "data": {
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Bug Fix Discussion",
      "markdownContent": "## Session Summary\n\n**User**: I'm having an issue with authentication...\n\n**Assistant**: Let me help you debug that...",
      "markdownSize": 15420,
      "metadata": {
        "clientName": "Cursor",
        "clientVersion": "2.0.0",
        "agentName": "SpecStory Agent",
        "deviceId": "device123",
        "gitBranches": ["main", "feature-auth"],
        "llmModels": ["claude-3-opus"],
        "tags": ["bug-fix", "authentication"]
      },
      "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",
      "project": {
        "id": "proj_abc123",
        "name": "My Web App",
        "icon": "Code2",
        "color": "blue"
      }
    }
  }
}

304 Not Modified

// No body - session hasn't changed since If-None-Match ETag

404 Not Found

{
  "success": false,
  "error": "Session not found"
}