SpecStory

https://docs.specstory.com/
Admin
SpecStory is an intent layer for modern software development that automatically captures and...
Tokens:54,060
Snippets:426
Trust Score:7.2
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install SpecStory CLI and Capture Sessions (macOS)

Source: https://docs.specstory.com/cloud/quickstart

This snippet shows how to install the SpecStory CLI using Homebrew on macOS and initiate capture sessions for various AI tools like Claude Code, Cursor CLI, Codex CLI, and Gemini CLI. It also includes commands to check the SpecStory version, perform a health check, and convert existing sessions to Markdown format.

```bash
brew tap specstoryai/tap
brew update
brew install specstory
specstory version
specstory check
specstory run claude # launches Claude Code and captures the session
specstory run cursor # launches Cursor CLI and captures the session
specstory run codex # launches Codex CLI and captures the session
specstory run gemini # launches Gemini CLI and captures the session
specstory sync # converts existing sessions to Markdown
```

--------------------------------

### Install and Verify Claude Code CLI

Source: https://docs.specstory.com/bearclaude/install

Installs the Claude Code CLI globally using npm, which is a prerequisite for BearClaude. It also includes a command to verify that the installation was successful and the CLI is accessible via the system's PATH.

```bash
# Prerequisite: Node.js 18+
# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Verify it’s on your PATH
claude --version
```

--------------------------------

### Authentication Examples: cURL, JavaScript, Python, Go

Source: https://docs.specstory.com/api-reference/authentication

Provides examples of making authenticated GET requests to the SpecStory Cloud API's /api/v1/projects endpoint across multiple programming languages. Demonstrates how to set the 'Authorization' and 'Content-Type' headers.

```bash
curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://cloud.specstory.com/api/v1/projects
```

```javascript
const response = await fetch('https://cloud.specstory.com/api/v1/projects', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
```

```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://cloud.specstory.com/api/v1/projects',
    headers=headers
)

data = response.json()
```

```go
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://cloud.specstory.com/api/v1/projects", nil)
    
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

--------------------------------

### Sync Projects with SpecStory Cloud using CLI

Source: https://docs.specstory.com/cloud/quickstart

These commands demonstrate how to sync local SpecStory sessions to the cloud using the command-line interface. The first command syncs all local sessions within the current repository, while the second allows syncing a specific session identified by its unique session ID. After syncing, users should refresh the SpecStory Cloud dashboard to see the updated project and sessions.

```bash
# Sync all local sessions in the current repo/project
specstory sync

# Sync a single session by ID
specstory sync claude -s <session-uuid>
```

--------------------------------

### Authenticate Device for SpecStory Cloud Sync

Source: https://docs.specstory.com/cloud/quickstart

This command is used to authenticate your local machine for uploading data to SpecStory Cloud. Running this command once per machine opens a browser for a secure login process. After successful authentication, a token is stored locally, which is used automatically for future sync operations.

```bash
specstory login
```

--------------------------------

### Fetch Project Sessions (cURL, JavaScript, Python)

Source: https://docs.specstory.com/api-reference/sessions/list-sessions

Examples demonstrating how to retrieve session data for a given project using cURL, JavaScript (fetch API), and Python (requests library). These examples require an API key for authentication and target the /api/v1/projects/{projectId}/sessions endpoint.

```bash
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()
```

--------------------------------

### Get Project with Sessions

Source: https://docs.specstory.com/api-reference/graphql-examples

Retrieve details of a specific project along with its recent sessions.

```APIDOC
## Get Project with Sessions

### Description
Retrieve details of a specific project, including its basic information and a list of its recent sessions. You can specify a limit for the number of sessions to retrieve.

### Method
POST

### Endpoint
/api/v1/graphql

### Parameters
#### Request Body
- **query** (String!) - The GraphQL query string.
- **variables** (Object) - Optional variables for the query.
  - **projectId** (ID!) - The ID of the project to retrieve.

### Request Example
#### Query
```graphql
query GetProjectWithSessions($projectId: ID!) {
  project(id: $projectId) {
    id
    name
    icon
    color
    sessions(limit: 10) {
      id
      name
      createdAt
      markdownSize
      metadata {
        clientName
        llmModels
        tags
      }
    }
  }
}
```

#### Variables
```json
{
  "projectId": "your-project-id"
}
```

### Response
#### Success Response (200)
- **project** (Object) - The project object.
  - **id** (ID) - The unique identifier for the project.
  - **name** (String) - The name of the project.
  - **icon** (String) - The icon associated with the project.
  - **color** (String) - The color associated with the project.
  - **sessions** (Array) - A list of recent session objects within the project.
    - **id** (ID) - The unique identifier for the session.
    - **name** (String) - The name of the session.
    - **createdAt** (DateTime) - The timestamp when the session was created.
    - **markdownSize** (Int) - The size of the session in markdown format.
    - **metadata** (Object) - Metadata associated with the session.
      - **clientName** (String) - The name of the client that generated the session.
      - **llmModels** (Array of String) - A list of LLM models used in the session.
      - **tags** (Array of String) - Tags associated with the session.

```json
{
  "data": {
    "project": {
      "id": "your-project-id",
      "name": "Example Project",
      "icon": "folder",
      "color": "#ffc107",
      "sessions": [
        {
          "id": "session-1",
          "name": "Initial Setup",
          "createdAt": "2024-01-15T09:30:00Z",
          "markdownSize": 5120,
          "metadata": {
            "clientName": "Web Interface",
            "llmModels": ["gpt-3.5-turbo"],
            "tags": ["setup", "configuration"]
          }
        }
        // ... more sessions
      ]
    }
  }
}
```
```

--------------------------------

### Manual Installation of SpecStory CLI (Linux/WSL)

Source: https://docs.specstory.com/integrations/codex-cli

Provides manual installation steps for SpecStory CLI on Linux or Windows Subsystem for Linux (WSL). This involves downloading binaries, making them executable, and placing them in the system's PATH.

```bash
tar -xzf SpecStoryCLI_Linux_x86_64.tar.gz   # unzip the Darwin archive on macOS
sudo mv specstory /usr/local/bin/
sudo chmod +x /usr/local/bin/specstory
specstory version
```

--------------------------------

### Fetch Session Details using JavaScript (fetch API)

Source: https://docs.specstory.com/api-reference/sessions/get-session

This example shows how to retrieve session data from the SpecStory API using the JavaScript fetch API. It constructs a GET request to the specified endpoint, including necessary headers for authentication and content type. The response is then parsed as JSON.

```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();
```

--------------------------------

### Get Project Sessions (JavaScript)

Source: https://docs.specstory.com/api-reference/sessions

This JavaScript example shows how to fetch project sessions using the Fetch API. It includes the necessary Authorization header with a bearer token and the project ID in the URL. The response is parsed as JSON, containing session data.

```javascript
async function getSessions(projectId, apiKey) {
  const response = await fetch(`https://cloud.specstory.com/api/v1/projects/${projectId}/sessions`, {
    headers: {
      "Authorization": `Bearer ${apiKey}`
    }
  });
  return await response.json();
}
```

--------------------------------

### List All Projects

Source: https://docs.specstory.com/api-reference/graphql-examples

Retrieve a list of all projects with their basic information.

```APIDOC
## List All Projects

### Description
Retrieve a list of all projects with their basic information, including ID, name, icon, color, creation timestamp, update timestamp, and session count.

### Method
POST

### Endpoint
/api/v1/graphql

### Request Body
```json
{
  "query": "query GetProjects {\n  projects {\n    id\n    name\n    icon\n    color\n    createdAt\n    updatedAt\n    sessionCount\n  }\n}"
}
```

### Response
#### Success Response (200)
- **projects** (Array) - A list of project objects.
  - **id** (ID) - The unique identifier for the project.
  - **name** (String) - The name of the project.
  - **icon** (String) - The icon associated with the project.
  - **color** (String) - The color associated with the project.
  - **createdAt** (DateTime) - The timestamp when the project was created.
  - **updatedAt** (DateTime) - The timestamp when the project was last updated.
  - **sessionCount** (Int) - The total number of sessions within the project.

```json
{
  "data": {
    "projects": [
      {
        "id": "project-1",
        "name": "SpecStory Website",
        "icon": "web",
        "color": "#007bff",
        "createdAt": "2023-10-26T10:00:00Z",
        "updatedAt": "2023-10-26T10:00:00Z",
        "sessionCount": 150
      }
      // ... more projects
    ]
  }
}
```
```

--------------------------------

### Get Project with Sessions - GraphQL

Source: https://docs.specstory.com/api-reference/graphql-examples

Fetches a specific project by its ID and includes a list of its recent sessions (limited to 10). It retrieves session details like ID, name, creation date, markdown size, and metadata such as client name and LLM models. Requires a 'projectId' variable.

```graphql
query GetProjectWithSessions($projectId: ID!) {
  project(id: $projectId) {
    id
    name
    icon
    color
    sessions(limit: 10) {
      id
      name
      createdAt
      markdownSize
      metadata {
        clientName
        llmModels
        tags
      }
    }
  }
}
```

```json
{
  "projectId": "your-project-id"
}
```

--------------------------------

### Install and Run SpecStory CLI

Source: https://docs.specstory.com/integrations/terminal-coding-agents/index

This snippet shows how to install the SpecStory CLI using Homebrew and then run your preferred AI coding agent (Claude, Cursor, or Codex) through SpecStory.

```bash
# 1. Install or update the SpecStory CLI
brew tap specstoryai/tap
brew update
brew install specstory

# 2. Run your preferred agent through SpecStory (choose one)
specstory run claude   # or cursor / codex

# 3. Export past sessions (pick the agent you used)
specstory sync claude  # or cursor / codex
```

--------------------------------

### Install SpecStory CLI using Homebrew

Source: https://docs.specstory.com/integrations/codex-cli

Installs the SpecStory CLI using Homebrew, a package manager for macOS. This is the primary method for installing SpecStory, which wraps the Codex CLI.

```bash
brew tap specstoryai/tap
brew update
brew install specstory
specstory version
specstory check
```

--------------------------------

### Markdown Lists Example

Source: https://docs.specstory.com/bearclaude/quickstart

Demonstrates how to create both bulleted and numbered lists within markdown.

```markdown
- bulleted
and
1. numbered
```

--------------------------------

### Verify BearClaude Capture Directory

Source: https://docs.specstory.com/bearclaude/install

Demonstrates the expected directory structure after BearClaude successfully captures a session. This involves creating a Markdown file with a spec, running it through Claude Code, and then checking the project folder for the generated `.specstory/history/` directory containing timestamped session files.

```bash
<your-project>/.specstory/history/
  └─ YYYY-MM-DD_HH-MM-SS_<session>.md
```

--------------------------------

### GraphQL Pagination for Large Datasets

Source: https://docs.specstory.com/api-reference/graphql-examples

Example of a GraphQL query utilizing cursor-based pagination to efficiently retrieve large datasets of sessions.

```graphql
query PaginatedSessions($cursor: String, $limit: Int = 20) {
  sessions(first: $limit, after: $cursor) {
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    edges {
      cursor
      node {
        id
        name
        createdAt
        project { name }
      }
    }
  }
}
```

--------------------------------

### Building a Dashboard

Source: https://docs.specstory.com/api-reference/graphql-examples

Aggregate data for building a dashboard, including recent activity, project overviews, and quick statistics.

```APIDOC
## Building a Dashboard

### Description
This query is designed to fetch data suitable for populating a dashboard, combining recent session activity, a summary of projects, and key usage statistics.

### Method
POST

### Endpoint
/api/v1/graphql

### Request Body
```json
{
  "query": "query DashboardData {\n  # Recent activity\n  recentSessions: sessions(limit: 5, orderBy: CREATED_AT_DESC) {\n    id\n    name\n    createdAt\n    project { name icon color }\n    metadata { llmModels }\n  }\n  \n  # Project overview\n  projects {\n    id\n    name\n    icon\n    color\n    sessionCount\n    lastActivity\n  }\n  \n  # Quick stats\n  stats {\n    totalSessions\n    totalProjects\n    sessionsThisWeek\n    topLLMModels(limit: 3) {\n      model\n      count\n    }\n  }\n}"
}
```

### Response
#### Success Response (200)
- **recentSessions** (Array) - List of the 5 most recent sessions.
  - **id** (ID) - Session ID.
  - **name** (String) - Session name.
  - **createdAt** (DateTime) - Session creation timestamp.
  - **project** (Object) - Project details.
    - **name** (String) - Project name.
    - **icon** (String) - Project icon.
    - **color** (String) - Project color.
  - **metadata** (Object) - Session metadata.
    - **llmModels** (Array of String) - LLM models used.
- **projects** (Array) - List of all projects.
  - **id** (ID) - Project ID.
  - **name** (String) - Project name.
  - **icon** (String) - Project icon.
  - **color** (String) - Project color.
  - **sessionCount** (Int) - Number of sessions in the project.
  - **lastActivity** (DateTime) - Timestamp of the last activity in the project.
- **stats** (Object) - Overall statistics.
  - **totalSessions** (Int) - Total number of all sessions.
  - **totalProjects** (Int) - Total number of projects.
  - **sessionsThisWeek** (Int) - Number of sessions this week.
  - **topLLMModels** (Array) - Top 3 LLM models.
    - **model** (String) - Model name.
    - **count** (Int) - Number of sessions using the model.

```json
{
  "data": {
    "recentSessions": [
      {
        "id": "session-jkl",
        "name": "Dashboard Implementation",
        "createdAt": "2024-05-20T15:00:00Z",
        "project": {"name": "Web App", "icon": "browser", "color": "#6610f2"},
        "metadata": {"llmModels": ["gpt-4o"]}
      }
      // ... 4 more recent sessions
    ],
    "projects": [
      {
        "id": "project-1",
        "name": "SpecStory Website",
        "icon": "web",
        "color": "#007bff",
        "sessionCount": 150,
        "lastActivity": "2024-05-20T14:30:00Z"
      }
      // ... more projects
    ],
    "stats": {
      "totalSessions": 35000
```

--------------------------------

### Project Statistics

Source: https://docs.specstory.com/api-reference/graphql-examples

Retrieve detailed statistics for a specific project.

```APIDOC
## Project Statistics

### Description
Retrieve comprehensive statistics for a specific project, including total sessions, total markdown size, unique LLM models used, sessions per day, and top tags.

### Method
POST

### Endpoint
/api/v1/graphql

### Parameters
#### Request Body
- **query** (String!) - The GraphQL query string.
- **variables** (Object) - Optional variables for the query.
  - **projectId** (ID!) - The ID of the project for which to retrieve statistics.

### Request Example
#### Query
```graphql
query ProjectStats($projectId: ID!) {
  project(id: $projectId) {
    id
    name
    stats {
      totalSessions
      totalMarkdownSize
      totalRawDataSize
      uniqueLLMModels
      uniqueGitBranches
      sessionsByDay(days: 30) {
        date
        count
      }
      topTags(limit: 10) {
        tag
        count
      }
    }
  }
}
```

#### Variables
```json
{
  "projectId": "your-project-id"
}
```

### Response
#### Success Response (200)
- **project** (Object) - The project object containing statistics.
  - **id** (ID) - The project ID.
  - **name** (String) - The project name.
  - **stats** (Object) - Statistics for the project.
    - **totalSessions** (Int) - Total number of sessions in the project.
    - **totalMarkdownSize** (Int) - Total size of session data in markdown format (bytes).
    - **totalRawDataSize** (Int) - Total size of session data in raw format (bytes).
    - **uniqueLLMModels** (Int) - Count of unique LLM models used.
    - **uniqueGitBranches** (Int) - Count of unique Git branches associated with sessions.
    - **sessionsByDay** (Array) - Daily session counts for a specified period.
      - **date** (Date) - The date.
      - **count** (Int) - The number of sessions on that date.
    - **topTags** (Array) - Top N tags used across sessions.
      - **tag** (String) - The tag name.
      - **count** (Int) - The number of sessions associated with the tag.

```json
{
  "data": {
    "project": {
      "id": "your-project-id",
      "name": "Example Project",
      "stats": {
        "totalSessions": 150,
        "totalMarkdownSize": 76800000,
        "totalRawDataSize": 153600000,
        "uniqueLLMModels": 5,
        "uniqueGitBranches": 12,
        "sessionsByDay": [
          {"date": "2024-05-18", "count": 5},
          {"date": "2024-05-19", "count": 8}
          // ... more dates
        ],
        "topTags": [
          {"tag": "api", "count": 45},
          {"tag": "documentation", "count": 30}
          // ... more tags
        ]
      }
    }
  }
}
```
```

--------------------------------

### Markdown Code Block Example

Source: https://docs.specstory.com/bearclaude/quickstart

Shows how to embed a JavaScript code block within a markdown document, with theme customization.

```markdown
```js
console.log("Hello, world!");
```
```

--------------------------------

### GET /api/v1/projects

Source: https://docs.specstory.com/api-reference/projects

Retrieves a list of projects associated with the authenticated user's account. Includes pagination and total count information.

```APIDOC
## GET /api/v1/projects

### Description
Retrieves a list of projects associated with the authenticated user's account. Includes pagination and total count information.

### Method
GET

### Endpoint
https://cloud.specstory.com/api/v1/projects

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer token for authentication

### Request Example
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://cloud.specstory.com/api/v1/projects
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Contains the project data
  - **projects** (array) - Array of project objects
    - **id** (string) - Unique project identifier
    - **ownerId** (string) - ID of the project owner
    - **name** (string) - Project name
    - **icon** (string) - Project icon identifier
    - **color** (string) - Project color theme
    - **createdAt** (string) - ISO 8601 creation timestamp
    - **updatedAt** (string) - ISO 8601 last update timestamp
  - **total** (number) - Total number of projects

#### Response Example
```json
{
  "success": true,
  "data": {
    "projects": [
      {
        "id": "proj_abc123xyz789",
        "ownerId": "user_def456uvw012",
        "name": "My Web App",
        "icon": "Code2",
        "color": "blue",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-20T14:45:30.000Z"
      },
      {
        "id": "proj_ghi789rst345",
        "ownerId": "user_def456uvw012",
        "name": "Mobile App Development",
        "icon": "Rocket",
        "color": "emerald",
        "createdAt": "2024-01-10T14:20:00.000Z",
        "updatedAt": "2024-01-18T09:15:00.000Z"
      }
    ],
    "total": 2
  }
}
```

#### Error Response (401)
- **success** (boolean) - Indicates if the request was successful
- **error** (string) - Error message detailing the issue (e.g., "Unauthorized")
```

--------------------------------

### Typical SpecStory Workflows

Source: https://docs.specstory.com/integrations/claude-code_sync-existing-claude-code-sessions

Illustrates common usage patterns for the SpecStory CLI. These examples demonstrate how to launch Claude Code with autosave, sync sessions, convert specific sessions, mirror logs, and use a custom Claude executable.

```bash
# Launch Claude Code with autosave enabled
specstory run

# Recreate any missing Markdown transcripts
specstory sync

# Convert a specific session by UUID
specstory sync -u <session-uuid>

# Mirror Claude logs in your terminal
specstory sync --console

# Use a custom Claude executable
specstory run -c "claude --dangerously-skip-permissions"
```

--------------------------------

### List All Projects - GraphQL

Source: https://docs.specstory.com/api-reference/graphql-examples

Retrieves a list of all projects, including their ID, name, icon, color, and creation/update timestamps. This query is useful for an overview of available projects.

```graphql
query GetProjects {
  projects {
    id
    name
    icon
    color
    createdAt
    updatedAt
    sessionCount
  }
}
```

--------------------------------

### GET /api/v1/projects/{projectId}/sessions

Source: https://docs.specstory.com/api-reference/sessions

Retrieves a list of sessions for a specific project. Requires authentication with a Bearer token.

```APIDOC
## GET /api/v1/projects/{projectId}/sessions

### Description
Retrieves a list of sessions associated with a given project ID. This endpoint is useful for fetching historical session data, including details about the client, agent, and LLM models used.

### Method
GET

### Endpoint
`/api/v1/projects/{projectId}/sessions`

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The unique identifier of the project.

#### Query Parameters
None

#### Request Body
None

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

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the session data.
  - **sessions** (array) - An array of session objects.
    - **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 about the session.
      - **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.

#### Response Example
```json
{
  "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"
  }
}
```

#### Error Response (401)
- **Unauthorized** - Indicates that the API key is invalid or missing.
```

--------------------------------

### Get Project Sessions (Python)

Source: https://docs.specstory.com/api-reference/sessions

This Python snippet illustrates how to retrieve project sessions using the `requests` library. It sends an authenticated GET request to the Specstory API, including the API key in the headers and the project ID in the URL. The response data is returned as a JSON object.

```python
import requests

def get_sessions(project_id, api_key):
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    url = f"https://cloud.specstory.com/api/v1/projects/{project_id}/sessions"
    response = requests.get(url, headers=headers)
    return response.json()
```

--------------------------------

### Fetch Recent Sessions (Python)

Source: https://docs.specstory.com/api-reference/sessions/get-recent-sessions

Example of fetching recent sessions using Python's requests library. It shows how to include the Authorization header and pass query parameters like 'limit'. The response is returned as JSON.

```python
import requests

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

data = response.json()
```

--------------------------------

### Fetch Recent Sessions (JavaScript)

Source: https://docs.specstory.com/api-reference/sessions/get-recent-sessions

Example of fetching recent sessions using JavaScript's fetch API. It demonstrates setting the Authorization header and parsing the JSON response. The endpoint is paginated with a 'limit' parameter.

```javascript
const response = await fetch('https://cloud.specstory.com/api/v1/sessions/recent?limit=10', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
```

--------------------------------

### Fetch Recent Sessions (cURL)

Source: https://docs.specstory.com/api-reference/sessions/get-recent-sessions

Example of fetching recent sessions using cURL. Requires an Authorization header with a bearer token. The request can be filtered by a 'limit' parameter.

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

--------------------------------

### GraphQL Error Response Structure

Source: https://docs.specstory.com/api-reference/graphql-examples

Example of a GraphQL error response. Errors are returned in the 'errors' array, providing details about the error message, location, path, and extensions.

```json
{
  "data": null,
  "errors": [
    {
      "message": "Project not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["project"],
      "extensions": {
        "code": "NOT_FOUND",
        "projectId": "invalid-id"
      }
    }
  ]
}
```

--------------------------------

### Example API Error Responses (JSON)

Source: https://docs.specstory.com/api-reference/errors

Illustrates various error scenarios with their corresponding JSON responses. These examples cover common issues like unauthorized access, forbidden actions, missing resources, and rate limiting.

```json
{
  "success": false,
  "error": "Invalid session token"
}
```

```json
{
  "success": false,
  "error": "Insufficient permissions to access this project"
}
```

```json
{
  "success": false,
  "error": "Project not found"
}
```

```json
{
  "success": false,
  "error": "Rate limit exceeded. Try again in 60 seconds."
}
```

--------------------------------

### Get Project Sessions (cURL)

Source: https://docs.specstory.com/api-reference/sessions

This snippet demonstrates how to retrieve a list of sessions for a given project using cURL. It requires an API key for authorization and specifies the project ID in the URL. The response includes session details and metadata.

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

--------------------------------

### GET /api/v1/projects

Source: https://docs.specstory.com/api-reference/authentication

This endpoint retrieves a list of projects. Authentication is required.

```APIDOC
## GET /api/v1/projects

### Description
Retrieves a list of projects associated with the authenticated user.

### Method
GET

### Endpoint
https://cloud.specstory.com/api/v1/projects

### Parameters

#### Request Headers
- **Authorization** (string) - Required - The JWT Bearer token for authentication.
- **Content-Type** (string) - Optional - Specifies the content type of the request body, typically `application/json`.
- **Accept** (string) - Optional - Specifies the desired response format, typically `application/json`.

### Request Example
```bash
curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://cloud.specstory.com/api/v1/projects
```

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.
- **success** (boolean) - Indicates if the request was successful.

#### Response Example
```json
{
  "projects": [
    {
      "id": "project-id-1",
      "name": "Example Project 1"
    },
    {
      "id": "project-id-2",
      "name": "Example Project 2"
    }
  ],
  "success": true
}
```

### Error Handling
#### 401 Unauthorized
Returned when the API key is missing, invalid, or expired.
```json
{
  "success": false,
  "error": "Invalid session token"
}
```

#### 403 Forbidden
Returned when the authenticated user lacks the necessary permissions to access the resource.
```json
{
  "success": false,
  "error": "Insufficient permissions"
}
```
```

--------------------------------

### Get Session

Source: https://docs.specstory.com/api-reference/sessions/get-session

Retrieves a specific session with its content and metadata. Supports conditional requests and content negotiation.

```APIDOC
## GET /websites/specstory/sessions/{sessionId}

### Description
Retrieve a specific session with its content and metadata.

### Method
GET

### Endpoint
/websites/specstory/sessions/{sessionId}

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The unique identifier of the session

#### Query Parameters
- **projectId** (string) - Required - The unique identifier of the project

#### Header Parameters
- **Authorization** (string) - Required - Bearer token for authentication
- **Accept** (string) - Optional - Content type for response. Options:
  * `application/json` (default) - Returns structured JSON
  * `text/markdown` - Returns raw markdown content
- **If-None-Match** (string) - Optional - ETag value for conditional requests

### Request Example
```json
{
  "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
```

### Response
#### Success Response (200)
- **sessionContent** (string) - The content of the session
- **metadata** (object) - Metadata associated with the session
```

--------------------------------

### SpecStory CLI Command Reference and Workflows

Source: https://docs.specstory.com/integrations/claude-code

Provides a reference for SpecStory CLI commands and common usage patterns. It outlines available commands like `check`, `run`, `sync`, and `version`, along with useful flags for customization and debugging. Example workflows demonstrate typical use cases.

```bash
Usage: specstory [command] [--flags]

Commands:
  check        Verify Claude Code can be invoked and autosave is configured
  run          Launch Claude Code with SpecStory capturing the session
  sync         Convert stored Claude Code sessions to Markdown
  version      Show SpecStory version information

Common flags:
  --console            Stream logs to stdout for easier debugging
  --debug              Include verbose diagnostics (requires --console or --log)
  --output-dir <path>  Write Markdown exports to a custom location
  --no-version-check   Skip the update check
  --silent             Reduce output to errors only

Typical workflows:

# Launch Claude Code with autosave enabled
specstory run

# Recreate any missing Markdown transcripts
specstory sync

# Convert a specific session by UUID
specstory sync -u <session-uuid>

# Mirror Claude logs in your terminal
specstory sync --console

# Use a custom Claude executable
specstory run -c "claude --dangerously-skip-permissions"
```

--------------------------------

### Fetch Session Details using Python (requests)

Source: https://docs.specstory.com/api-reference/sessions/get-session

This Python snippet illustrates how to make an API call to fetch session details using the 'requests' library. It configures the GET request with the correct URL and headers, including authorization. The JSON response is then extracted.

```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()
```

--------------------------------

### GraphQL Fragments for Reusable Fields

Source: https://docs.specstory.com/api-reference/graphql-examples

Demonstrates using GraphQL fragments to define reusable sets of fields, improving query readability and reducing redundancy.

```graphql
fragment SessionBasics on Session {
  id
  name
  createdAt
  markdownSize
  metadata {
    llmModels
    tags
  }
}

query GetSessions {
  recentSessions: sessions(limit: 10) {
    ...SessionBasics
  }
  
  searchResults: searchSessions(query: "React") {
    results {
      ...SessionBasics
      rank
      snippet
    }
  }
}
```

--------------------------------

### GET /websites/specstory/sessions

Source: https://docs.specstory.com/api-reference/sessions/get-recent-sessions

Retrieves the most recent sessions across all projects within SpecStory. Allows filtering by the number of sessions to return.

```APIDOC
## GET /websites/specstory/sessions

### Description
Retrieve the most recent sessions across all projects.

### Method
GET

### Endpoint
/websites/specstory/sessions

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of sessions to return (1-100). Defaults to 5.

#### Header Parameters
- **Authorization** (string) - Required - Bearer token for authentication

### Request Example
```json
{
  "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
```

### Response
#### Success Response (200)
- **sessions** (array) - A list of recent session objects.
  - **sessionId** (string) - The unique identifier for the session.
  - **projectId** (string) - The identifier of the project the session belongs to.
  - **timestamp** (string) - The timestamp when the session occurred.

#### Response Example
```json
{
  "sessions": [
    {
      "sessionId": "sess_abc123",
      "projectId": "proj_xyz789",
      "timestamp": "2023-10-27T10:00:00Z"
    },
    {
      "sessionId": "sess_def456",
      "projectId": "proj_uvw012",
      "timestamp": "2023-10-27T09:30:00Z"
    }
  ]
}
```
```

--------------------------------

### GraphQL Query with Variables for Reusability

Source: https://docs.specstory.com/api-reference/graphql

Shows how to use variables in GraphQL queries to make them dynamic and reusable. This example retrieves a specific project's details and its first 5 sessions, demonstrated with cURL and JavaScript.

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "query GetProject($projectId: ID!) { project(id: $projectId) { id name sessions(limit: 5) { id name } } }", \
    "variables": {"projectId": "proj_123"} \
  }' \
  https://cloud.specstory.com/api/v1/graphql
```

```javascript
const response = await fetch('https://cloud.specstory.com/api/v1/graphql', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `
      query GetProject($projectId: ID!) {
        project(id: $projectId) {
          id
          name
          sessions(limit: 5) {
            id
            name
          }
        }
      }
    `,
    variables: {
      projectId: 'proj_123'
    }
  })
});
```

--------------------------------

### Fetch Session Details using cURL

Source: https://docs.specstory.com/api-reference/sessions/get-session

This snippet demonstrates how to fetch session details from the SpecStory API using a cURL command. It includes setting the Authorization header with your API key and the Accept header for JSON format. The endpoint requires the project ID and session ID.

```bash
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
```

--------------------------------

### Usage Analytics

Source: https://docs.specstory.com/api-reference/graphql-examples

Retrieve aggregated usage analytics data for a specified time range.

```APIDOC
## Usage Analytics

### Description
Retrieve aggregated analytics data, including total sessions, total projects, sessions by model, sessions by client, and daily activity, for a specified time range.

### Method
POST

### Endpoint
/api/v1/graphql

### Parameters
#### Request Body
- **query** (String!) - The GraphQL query string.
- **variables** (Object) - Optional variables for the query.
  - **timeRange** (TimeRange!) - The time range for which to retrieve analytics.
    - **start** (DateTime!) - The start date of the range (inclusive).
    - **end** (DateTime!) - The end date of the range (inclusive).

### Request Example
#### Query
```graphql
query UsageAnalytics($timeRange: TimeRange!) {
  analytics(timeRange: $timeRange) {
    totalSessions
    totalProjects
    sessionsByModel {
      model
      count
      totalSize
    }
    sessionsByClient {
      client
      count
      averageSize
    }
    activityByDay {
      date
      sessions
      projects
    }
  }
}
```

#### Variables
```json
{
  "timeRange": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  }
}
```

### Response
#### Success Response (200)
- **analytics** (Object) - The aggregated analytics object.
  - **totalSessions** (Int) - Total number of sessions within the time range.
  - **totalProjects** (Int) - Total number of projects active within the time range.
  - **sessionsByModel** (Array) - Aggregated session counts and sizes by LLM model.
    - **model** (String) - The LLM model name.
    - **count** (Int) - Number of sessions using this model.
    - **totalSize** (Int) - Total size of data processed by this model (bytes).
  - **sessionsByClient** (Array) - Aggregated session counts and average sizes by client.
    - **client** (String) - The client name.
    - **count** (Int) - Number of sessions initiated by this client.
    - **averageSize** (Float) - Average session size for this client (bytes).
  - **activityByDay** (Array) - Daily activity summary.
    - **date** (Date) - The date.
    - **sessions** (Int) - Number of sessions on that date.
    - **projects** (Int) - Number of active projects on that date.

```json
{
  "data": {
    "analytics": {
      "totalSessions": 12500,
      "totalProjects": 300,
      "sessionsByModel": [
        {"model": "gpt-4", "count": 5000, "totalSize": 1000000000},
        {"model": "claude-3-opus", "count": 4000, "totalSize": 900000000}
        // ... more models
      ],
      "sessionsByClient": [
        {"client": "Web Interface", "count": 8000, "averageSize": 12000},
        {"client": "Developer IDE", "count": 4500, "averageSize": 15000}
        // ... more clients
      ],
      "activityByDay": [
        {"date": "2024-01-01", "sessions": 400, "projects": 150},
        {"date": "2024-01-02", "sessions": 420, "projects": 155}
        // ... more dates
      ]
    }
  }
}
```
```
Tokens:
Raw