### Start Local Development Server

Source: https://github.com/specstoryai/docs/blob/main/README.md

Run this command from the root of your documentation directory, where mint.json is located, to start the local development server.

```bash
mintlify dev
```

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

### Install and Run SpecStory CLI

Source: https://github.com/specstoryai/docs/blob/main/integrations/terminal-coding-agents/index.mdx

Install the SpecStory CLI using Homebrew and run your preferred AI agent through the SpecStory wrapper. This setup allows SpecStory to capture terminal conversations.

```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://github.com/specstoryai/docs/blob/main/integrations/codex-cli.mdx

Install the SpecStory CLI using Homebrew. This command taps the repository, updates, installs the CLI, and checks the version and installation.

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

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

### Manual SpecStory CLI Installation

Source: https://github.com/specstoryai/docs/blob/main/integrations/codex-cli.mdx

Manually install the SpecStory CLI by downloading binaries, making them executable, and moving them to your PATH. This is useful for Linux, WSL, or manual installations.

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

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

### Install Mintlify CLI

Source: https://github.com/specstoryai/docs/blob/main/README.md

Use this command to install the Mintlify CLI globally. This tool is required for previewing documentation changes locally.

```bash
npm i -g mintlify
```

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

### Install and Run SpecStory CLI for Claude Code

Source: https://github.com/specstoryai/docs/blob/main/quickstart.mdx

Install the SpecStory CLI using Homebrew and then run Claude through the SpecStory wrapper. This setup captures Claude Code sessions.

```bash
brew tap specstoryai/tap
brew update
brew install specstory
specstory run claude
specstory sync claude
```

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

### Install SpecStory CLI Binary on Linux/WSL

Source: https://github.com/specstoryai/docs/blob/main/specstory/introduction.mdx

Install the SpecStory CLI on Linux or WSL by downloading the binary. Includes steps for extraction, PATH configuration, verification, and usage.

```bash
unzip SpecStoryCLI_*.zip
sudo mv specstory /usr/local/bin/
chmod +x /usr/local/bin/specstory
```

```bash
specstory version
specstory check
```

```bash
# Run Claude Code through SpecStory wrapper
specstory run claude

# Run Cursor CLI through SpecStory wrapper
specstory run cursor

# Run Codex CLI through SpecStory wrapper
specstory run codex

# Or sync existing sessions to markdown
specstory sync
```

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

### Install AIrgap CLI

Source: https://github.com/specstoryai/docs/blob/main/airgap.mdx

Installs the AIrgap command-line tool. Ensure the release-path is correct for your system.

```bash
curl -L [release-path] -o airgap
chmod +x airgap
sudo mv airgap /usr/local/bin/
```

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

### Fetch a Specific Session using JavaScript

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/get-session.mdx

This JavaScript example demonstrates how to make a GET request to fetch session details. It includes setting the necessary authorization and accept headers.

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

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

### Install SpecStory CLI with Homebrew

Source: https://github.com/specstoryai/docs/blob/main/specstory/introduction.mdx

Use Homebrew to install the SpecStory CLI on macOS. This method also covers verification and upgrading.

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

```bash
specstory version
specstory check
```

```bash
# Run Claude Code through SpecStory wrapper
specstory run claude

# Run Cursor CLI through SpecStory wrapper
specstory run cursor

# Run Codex CLI through SpecStory wrapper
specstory run codex

# Run Gemini CLI through SpecStory wrapper
specstory run gemini

# Or sync existing sessions to markdown
specstory sync
```

```bash
brew update
brew upgrade specstory
```

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

### Install and Run SpecStory CLI for Cursor CLI

Source: https://github.com/specstoryai/docs/blob/main/quickstart.mdx

Install the SpecStory CLI using Homebrew and then run Cursor CLI through the SpecStory wrapper. This allows capturing Cursor CLI sessions and exporting past chats.

```bash
brew tap specstoryai/tap
brew update
brew install specstory
specstory run cursor
specstory sync cursor
```

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

### Install and Run SpecStory CLI for Gemini CLI

Source: https://github.com/specstoryai/docs/blob/main/quickstart.mdx

Install the SpecStory CLI using Homebrew and then launch Gemini CLI via SpecStory. This archives Gemini-driven workflows.

```bash
brew tap specstoryai/tap
brew update
brew install specstory
specstory run gemini
specstory sync gemini
```

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

### Successful Response Example

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/list-sessions.mdx

This is an example of a successful response when listing sessions. It includes details about the sessions found, total count, and project ID.

```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"
  }
}
```

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

### Delete Project Request Examples

Source: https://github.com/specstoryai/docs/blob/main/api-reference/projects/delete-project.mdx

Use these examples to delete a project. Ensure you replace 'YOUR_API_KEY' with your actual API key and 'proj_abc123' with the target project ID. This action is irreversible and will delete all sessions within the project.

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

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

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

```Python
import requests

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

data = response.json()
```

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

### Authenticate API Request with Go

Source: https://github.com/specstoryai/docs/blob/main/api-reference/authentication.mdx

This Go example demonstrates how to set up an HTTP client and request to include the necessary `Authorization` and `Content-Type` headers for API authentication.

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

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

### Install and Run SpecStory CLI for Codex CLI

Source: https://github.com/specstoryai/docs/blob/main/quickstart.mdx

Install the SpecStory CLI using Homebrew and then launch Codex CLI via SpecStory. This archives GPT-driven workflows.

```bash
brew tap specstoryai/tap
brew update
brew install specstory
specstory run codex
specstory sync codex
```

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

### List Projects using JavaScript

Source: https://github.com/specstoryai/docs/blob/main/api-reference/projects/list-projects.mdx

Fetch all projects in your workspace using JavaScript. This example uses the Fetch API and requires your Bearer token for authentication.

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

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

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

### Verify SpecStory CLI Installation

Source: https://github.com/specstoryai/docs/blob/main/cloud/quickstart.mdx

Checks the installed SpecStory CLI version and performs a health check. This is a prerequisite before running capture agents.

```bash
specstory version
specstory check
```

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

### List Sessions using Python

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/list-sessions.mdx

This Python example shows how to retrieve a list of sessions for a project using the requests library. Replace YOUR_API_KEY and proj_abc123 with your specific values.

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

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

### Example Error Responses

Source: https://github.com/specstoryai/docs/blob/main/api-reference/errors.mdx

Illustrative examples of error responses for common HTTP status codes, demonstrating the expected JSON payload.

```APIDOC
### Example Error Responses

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

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

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

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

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

### Run Claude Code with SpecStory

Source: https://github.com/specstoryai/docs/blob/main/integrations/claude-code.mdx

Start Claude Code through SpecStory to automatically capture session output as Markdown in the `.specstory/history/` directory.

```bash
specstory run claude
```

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

### Authenticate API Request with cURL (Full Example)

Source: https://github.com/specstoryai/docs/blob/main/api-reference/authentication.mdx

A complete cURL command to authenticate and fetch projects from the SpecStory Cloud API.

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

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

### Fetch Recent Sessions (Python)

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/get-recent-sessions.mdx

This Python example uses the requests library to fetch recent sessions. It shows how to set the Authorization header and pass query parameters like 'limit'.

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

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

### GraphQL Error Handling Example

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-examples.mdx

Illustrates the structure of a GraphQL error response, including message, locations, 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"
      }
    }
  ]
}
```

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

### List All Projects GraphQL Query

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-examples.mdx

Use this query to retrieve a list of all projects, including their basic information and session counts. No specific setup is required beyond a valid API token.

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

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

### AIrgap Allowed Change Notification

Source: https://github.com/specstoryai/docs/blob/main/airgap.mdx

Example output when a change is permitted by AIrgap rules.

```bash
✅ Change allowed: src/features/search/index.js
```

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

### Successful Project List Response

Source: https://github.com/specstoryai/docs/blob/main/api-reference/projects/list-projects.mdx

This is an example of a successful response when listing projects. It includes an array of project objects and the total count.

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

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

### Execute GraphQL Query with Python

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-endpoint.mdx

This Python example uses the 'requests' library to send a POST request to the GraphQL endpoint. It shows how to define the query and variables, and how to include the Authorization header in the request.

```python
import requests

query = """
query SearchSessions($query: String!) {
  searchSessions(query: $query, limit: 10) {
    total
    results {
      id
      name
      rank
    }
  }
}
"""

variables = {
    "query": "authentication bug fix"
}

response = requests.post(
    'https://cloud.specstory.com/api/v1/graphql',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'query': query, 'variables': variables}
)

data = response.json()
```

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

### Feature-Specific Airgap Configuration

Source: https://github.com/specstoryai/docs/blob/main/airgap.mdx

Define custom Airgap configurations using named files. This example locks all files by default and then explicitly allows modifications within the 'search' module and its documentation.

```bash
# .airgap.search-feature
!**                  # Lock everything
src/search/**        # Allow only search module
tests/search/**      # And its tests
docs/search.md       # And documentation
```

```bash
airgap search-feature
```

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

### Successful Project Update Response

Source: https://github.com/specstoryai/docs/blob/main/api-reference/projects/update-project.mdx

This is an example of a successful response when updating a project. It confirms the operation was successful and returns the updated project details.

```json
{
  "success": true,
  "data": {
    "name": "Updated Name",
    "icon": "Rocket",
    "color": "emerald"
  }
}
```

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

### GraphQL Query for Precise Field Selection

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql.mdx

Illustrates how to select only the necessary fields in a GraphQL query, ensuring efficient data retrieval. This example fetches session IDs, names, and creation timestamps.

```graphql
{
  sessions(limit: 10) {
    id
    name
    # Only get the fields you need
    createdAt
  }
}
```

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

### Basic GraphQL Query

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql.mdx

Send a JSON payload with a 'query' field to execute a basic GraphQL query. This example retrieves project IDs, names, and session counts.

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects { id name sessionCount } }"}' \
  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: `{
      projects {
        id
        name
        sessionCount
      }
    }`
  })
});

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

```python
import requests

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

query = """
{
  projects {
    id
    name
    sessionCount
  }
}
"""

response = requests.post(
    'https://cloud.specstory.com/api/v1/graphql',
    headers=headers,
    json={'query': query}
)

data = response.json()
```

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

### Get Project with Sessions

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-examples.mdx

Retrieves a specific project by its ID and includes a limited list of its associated sessions, along with session details and metadata.

```APIDOC
## Get Project with Sessions

### Description
Retrieves a specific project by its ID and includes a limited list of its associated sessions, along with session details and metadata.

### Method
GraphQL Query

### Endpoint
/api/v1/graphql

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

### Parameters
#### Query Parameters
- **projectId** (ID!) - Required - The ID of the project to retrieve.

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

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

### Successful Response Example

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/get-recent-sessions.mdx

A successful API response for fetching recent sessions. It includes a 'success' flag, and a 'data' object containing an array of 'sessions' and the 'total' count.

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

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

### GraphQL Query with Variables

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql.mdx

Use variables in your GraphQL queries for reusability and cleaner syntax, especially for complex operations. This example fetches a specific project and its sessions.

```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'
    }
  })
});
```

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

### Set API Key as Environment Variable

Source: https://github.com/specstoryai/docs/blob/main/api-reference/authentication.mdx

Store your API key in an environment variable for secure and convenient access. This example shows how to set it in Bash and use it with `curl`.

```bash
export SPECSTORY_API_KEY="your_api_key_here"

curl -H "Authorization: Bearer $SPECSTORY_API_KEY" \
  https://cloud.specstory.com/api/v1/projects
```

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

### Get Project with Sessions GraphQL Query

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-examples.mdx

Retrieve details for a specific project along with a limited number of its associated sessions. You must provide a valid project ID. The session limit can be adjusted.

```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"
}
```

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

### Get Session

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/get-session.mdx

Retrieves a specific session's content and metadata.

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

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

### Method
GET

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

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

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

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

### Authenticate and Sync with SpecStory CLI

Source: https://github.com/specstoryai/docs/blob/main/cloud/sync-and-store.mdx

Use these commands to authenticate your device with SpecStory Cloud and sync local session histories. Run `specstory login` once per machine. Then, use `specstory sync` to upload all local sessions or `specstory sync -u <session-uuid>` to sync a specific session.

```bash
# Authenticate device (run once)
specstory login

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

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

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

### List Projects using cURL

Source: https://github.com/specstoryai/docs/blob/main/api-reference/projects/list-projects.mdx

Use this command to list all projects in your workspace. Ensure you replace YOUR_API_KEY with your actual authentication token.

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

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

### Schema Introspection

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql.mdx

GraphQL is self-documenting. You can query the schema itself or get information about specific types.

```APIDOC
## Schema Introspection

### Querying the Schema
To get a list of all types and their descriptions:
```graphql
{
  __schema {
    types {
      name
      description
    }
  }
}
```

### Querying Specific Types
To get information about a specific type, such as 'Session':
```graphql
{
  __type(name: "Session") {
    name
    fields {
      name
      type {
        name
      }
    }
  }
}
```
```

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

### Get Recent Sessions

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/get-recent-sessions.mdx

Fetches a list of recent sessions. You can specify a limit for the number of sessions to retrieve.

```APIDOC
## GET /sessions/recent

### Description
Retrieves a list of recent sessions for the authenticated project. Supports a `limit` query parameter to control the number of results.

### Method
GET

### Endpoint
/api/v1/sessions/recent

### Query Parameters
- **limit** (number) - Optional - The maximum number of sessions to return.

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

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

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

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the session data.
  - **sessions** (array) - Array of recent 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) - Additional 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.
  - **total** (number) - Total number of sessions returned.

#### Response Example (200 Success)
```json
{
  "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"]
        }
      }
    ],
    "total": 1
  }
}
```

#### Error Response (401 Unauthorized)
- **success** (boolean) - Indicates if the request was successful.
- **error** (string) - Error message.

#### Response Example (401 Unauthorized)
```json
{
  "success": false,
  "error": "Invalid or missing authentication token"
}
```
```

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

### Build a Dashboard with GraphQL

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-examples.mdx

Use this query to fetch data for building a dashboard, including recent activity, project overviews, and quick statistics.

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

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

### Get Recent Sessions

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/get-recent-sessions.mdx

Retrieves the most recent sessions across all projects. You can specify the number of sessions to return.

```APIDOC
## GET /api/v1/sessions/recent

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

### Method
GET

### Endpoint
/api/v1/sessions/recent

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

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

### List Sessions using JavaScript

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/list-sessions.mdx

This JavaScript snippet demonstrates how to fetch a list of sessions for a project using the Fetch API. Remember to include your API key in the Authorization header.

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

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

### Get Session by ID

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/get-session.mdx

Fetches a specific session's details using its project ID and session ID.

```APIDOC
## GET /projects/{projectId}/sessions/{sessionId}

### Description
Retrieves the details of a specific session, identified by its unique session ID, within a given project.

### Method
GET

### Endpoint
/projects/{projectId}/sessions/{sessionId}

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

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the session data.
  - **session** (object) - The session object.
    - **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 associated with 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.
    - **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 details.
      - **id** (string) - Project ID.
      - **name** (string) - Project name.
      - **icon** (string) - Project icon.
      - **color** (string) - Project color.

#### Error Response (404 Not Found)
- **success** (boolean) - Indicates if the request was successful.
- **error** (string) - Error message, e.g., "Session not found".

### Request Example
```bash 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 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 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 Example (200 Success)
```json
{
  "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"
      }
    }
  }
}
```

### Response Example (304 Not Modified)
```json
// No body - session hasn't changed since If-None-Match ETag
```

### Response Example (404 Not Found)
```json
{
  "success": false,
  "error": "Session not found"
}
```
```

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

### Re-install Mintlify Dependencies

Source: https://github.com/specstoryai/docs/blob/main/README.md

If 'mintlify dev' is not running, execute this command to re-install dependencies. This can resolve issues with the development server.

```bash
mintlify install
```

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

### Authenticate GraphQL Request

Source: https://github.com/specstoryai/docs/blob/main/api-reference/authentication.mdx

This example demonstrates how to authenticate a GraphQL POST request using a Bearer token in the Authorization header.

```APIDOC
## POST /api/v1/graphql

### Description
Send a POST request to the GraphQL endpoint with your API key as a Bearer token in the Authorization header to authenticate your request.

### Method
POST

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

### Request Body
- **query** (string) - Required - The GraphQL query string.

### Request Example
```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects { id name } }"}' \
  https://cloud.specstory.com/api/v1/graphql
```

### Response
#### Success Response (200)
- **data** (object) - Contains the result of the GraphQL query.
- **errors** (array) - Contains any errors encountered during query execution.
```

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

### Run AI Capture Agents with SpecStory CLI

Source: https://github.com/specstoryai/docs/blob/main/cloud/quickstart.mdx

Launches and captures sessions from various AI tools using the SpecStory CLI. Use `specstory sync` to convert captured sessions to Markdown.

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

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

### AIrgap Protected File Modification Error

Source: https://github.com/specstoryai/docs/blob/main/airgap.mdx

Example error message when attempting to modify a file protected by AIrgap rules.

```bash
❌ Protected file modified: src/auth/login.js (rule: !src/auth/**)
```

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

### Typical SpecStory Workflows

Source: https://github.com/specstoryai/docs/blob/main/integrations/claude-code.mdx

Common workflows for launching Claude Code with autosave, recreating transcripts, syncing specific sessions, mirroring logs, and using custom Claude executables.

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

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

### Authenticate Device with SpecStory CLI

Source: https://github.com/specstoryai/docs/blob/main/cloud/quickstart.mdx

Run this command once per machine to authenticate your device for CLI and extension uploads. It opens a browser for a secure login and stores a token locally for future use.

```bash
specstory login
```

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

### Successful Authentication Response

Source: https://github.com/specstoryai/docs/blob/main/api-reference/authentication.mdx

This is an example of a successful JSON response when testing authentication. It indicates that your API key is valid and your request was processed correctly.

```json
{
  "success": true,
  "data": {
    "projects": [...],
    "total": 5
  }
}
```

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

### List Sessions using cURL

Source: https://github.com/specstoryai/docs/blob/main/api-reference/sessions/list-sessions.mdx

Use this command to list sessions for a project via cURL. Ensure you replace YOUR_API_KEY and proj_abc123 with your actual credentials and project ID.

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

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

### Sync Local Sessions with SpecStory CLI

Source: https://github.com/specstoryai/docs/blob/main/cloud/quickstart.mdx

Use these commands to sync local sessions. The first syncs all sessions in the current project, while the second syncs a specific session by its ID.

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

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

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

### GraphQL Error Response Structure

Source: https://github.com/specstoryai/docs/blob/main/api-reference/errors.mdx

Example of a GraphQL response containing both partial data and an 'errors' array. This structure is used when operations encounter issues.

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

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

### Project Statistics

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-examples.mdx

Get aggregated statistics for a specific project, including total sessions, markdown size, unique models, and session counts by day.

```APIDOC
## Project Statistics

### Description
Get aggregated statistics for a specific project, including total sessions, markdown size, unique models, and session counts by day.

### 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
      }
    }
  }
}
```
```

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

### Setting Environment Variable and Making a Request

Source: https://github.com/specstoryai/docs/blob/main/api-reference/authentication.mdx

Demonstrates how to set your API key as an environment variable and use it to authenticate requests to the SpecStory API across different languages.

```Bash
export SPECSTORY_API_KEY="your_api_key_here"

curl -H "Authorization: Bearer $SPECSTORY_API_KEY" \
  https://cloud.specstory.com/api/v1/projects
```

```Node.js
// Using process.env
const apiKey = process.env.SPECSTORY_API_KEY;

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

```Python
import os
import requests

api_key = os.getenv('SPECSTORY_API_KEY')

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

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

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

### Building a Dashboard

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-examples.mdx

Fetch data to populate a dashboard, including recent activity, project overviews, and key statistics.

```APIDOC
## DashboardData

### Description
Retrieves data for building a dashboard, including recent sessions, project summaries, and overall statistics.

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

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

### GraphQL Query for Multiple Resources

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql.mdx

Demonstrates fetching data from multiple related resources (projects and their sessions) in a single GraphQL request, highlighting a key advantage over REST.

```graphql
{
  projects {
    id
    name
    sessions(limit: 3) {
      id
      name
      metadata {
        llmModels
        tags
      }
    }
  }
}
```

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

### List All Projects

Source: https://github.com/specstoryai/docs/blob/main/api-reference/graphql-examples.mdx

Retrieves a list of all projects, including their basic information such as ID, name, icon, color, and timestamps.

```APIDOC
## List All Projects

### Description
Retrieves a list of all projects, including their basic information such as ID, name, icon, color, and timestamps.

### Method
GraphQL Query

### Endpoint
/api/v1/graphql

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