Specstory

https://github.com/specstoryai/docs
Admin
Specstory provides documentation for its platform, allowing users to feed extensive documentation...
Tokens:54,742
Snippets:461
Trust Score:7.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Mintlify CLI

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

Installs the Mintlify CLI globally to preview documentation changes locally.

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

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

### Authentication Examples in Multiple Languages

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

These examples show how to make an authenticated GET request to the SpecStory Cloud API in cURL, JavaScript, Python, and Go. Each example includes the Authorization header with the Bearer scheme and the Content-Type header. Replace YOUR_API_KEY with your actual API key.

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

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

### Install SpecStory CLI via Homebrew and verify

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

Install or update the SpecStory CLI on macOS so it can wrap `claude` and archive session output. After installing, run `specstory version` and `specstory check` to verify the setup.

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

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

### Install and run SpecStory with Gemini CLI

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

Install the SpecStory CLI via Homebrew, then launch Gemini CLI through the wrapper and sync the captured history.

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

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

### Install AIrgap with curl and chmod and mv

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

Downloads the airgap binary from a release path, makes it executable, and moves it to /usr/local/bin/ for system-wide installation.

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

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

### Manual Linux/WSL install from release archive

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

Alternative installation for Linux or WSL when the Homebrew formula is not available. Download the archive matching your OS and architecture from the latest release, extract it, then move and make the binary executable.

```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 and run SpecStory with Claude Code

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

Install the SpecStory CLI via Homebrew, then run Claude through the wrapper and sync the captured history.

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

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

### Universal workflow: install SpecStory CLI and run/sync agents

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

Shows the complete workflow: install the SpecStory CLI via Homebrew, run an agent through SpecStory with `specstory run`, and export past sessions with `specstory sync`. Transcripts are saved to `.specstory/history/`.

```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 and run SpecStory with Cursor CLI

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

Install the SpecStory CLI via Homebrew, then run Cursor CLI through the wrapper and sync the captured history.

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

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

### Install and run SpecStory with Codex CLI

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

Install the SpecStory CLI via Homebrew, then launch Codex CLI through the wrapper and sync the captured history.

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

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

### Install SpecStory CLI on Linux/WSL

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

Install SpecStory CLI on Linux or WSL by downloading the binary, extracting it, and moving it to /usr/local/bin. Verify with `specstory version` and `specstory check`, then run terminal agents through the wrapper or sync existing sessions.

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

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

### Get Recent Sessions - Request Examples (cURL, JavaScript, Python)

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

Request examples for the Get Recent Sessions endpoint. All three variants use the same endpoint and require an Authorization header with a bearer token. The optional limit query parameter is set to 10 in these examples.

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

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

### GraphQL Response Format Example

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

Example response format for a GraphQL query. The data field contains the requested projects array.

```json
{
  "data": {
    "projects": [
      {
        "id": "proj_123",
        "name": "My Web App",
        "sessionCount": 15
      },
      {
        "id": "proj_789",
        "name": "Mobile App",
        "sessionCount": 8
      }
    ]
  }
}
```

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

### List Projects API Request (cURL, JavaScript, Python)

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

Send a GET request to the List Projects endpoint with a Bearer token. The cURL, JavaScript, and Python examples are equivalent ways to retrieve all projects in the workspace.

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  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'
  }
});

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

```python
import requests

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

data = response.json()
```

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

### Update Project - 404 Not Found Response

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

Example error response when the project is not found.

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

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

### List All Projects (GraphQL Query)

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

Fetches basic project information including session counts. Use this to get an overview of all projects.

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

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

### Delete Project Response Examples

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

Response examples for the delete project endpoint. The 200 Success response includes the deleted project details and a deletion timestamp. The 403 Forbidden response indicates insufficient permissions, and the 404 Not Found response indicates the project does not exist.

```json
{
  "success": true,
  "data": {
    "deletedProject": {
      "id": "proj_abc123",
      "ownerId": "user_def456",
      "name": "My Web App",
      "icon": "Code2",
      "color": "blue",
      "createdAt": "2024-01-10T08:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "deletedAt": "2024-01-15T11:00:00.000Z"
  }
}
```

```json
{
  "success": false,
  "error": "You do not have permission to delete this project"
}
```

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

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

### Get Recent Sessions - Response Examples (200 Success, 401 Unauthorized)

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

Response examples for the Get Recent Sessions endpoint. The 200 Success response shows the structure of the sessions array with fields like id, projectId, name, markdownSize, rawDataSize, timestamps, and metadata. The 401 Unauthorized response indicates an invalid or missing authentication token.

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

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

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

### GET /api/v1/sessions/recent

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

This snippet documents the GET /api/v1/sessions/recent endpoint, including its query parameters, request examples in cURL, JavaScript, and Python, and the full response schema with success and error examples.

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

### Description
Retrieves a list of recent sessions for the authenticated user. The response includes session details such as IDs, timestamps, and metadata.

### Method
GET

### Endpoint
`https://cloud.specstory.com/api/v1/sessions/recent`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of sessions to return. Example: `limit=10`.

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

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the response 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) - Session 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.

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

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

#### Error Example
```json
{
  "success": false,
  "error": "Invalid or missing authentication token"
}
```
```

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

### 404 Not Found Response

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

Example error response when the specified session does not exist.

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

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

### 200 Success Response for List Sessions

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

Example successful response containing session data, including metadata fields like clientName, gitBranches, and llmModels.

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

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

### Example Error Responses for 401, 403, 404, and 429

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

Example error responses for HTTP status codes 401, 403, 404, and 429, showing the error messages returned for each condition.

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

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

### Run SpecStory CLI on Linux/WSL

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

After downloading the latest release from GitHub, run the SpecStory CLI to check the installation, launch terminal agent sessions, and sync existing sessions to Markdown.

```bash
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 Cursor CLI and captures the session
specstory run gemini # launches Gemini CLI and captures the session
specstory sync # converts existing sessions to Markdown
```

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

### Check Session with JavaScript

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

Use this JavaScript fetch example to send a HEAD request and check if the session exists. Logs the ETag header if the response is OK.

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

// Check status
if (response.ok) {
  console.log('Session exists');
  console.log('ETag:', response.headers.get('ETag'));
}
```

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

### GraphQL Error Handling Response Example

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

GraphQL errors are returned in the errors array alongside any successful data. The example shows a NOT_FOUND error with location, path, and extensions.

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

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

### Update Project - 200 Success Response

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

Example successful response indicating the project was updated.

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

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

### Basic GraphQL Query for Projects (cURL, JavaScript, Python)

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

Send a basic GraphQL query to retrieve projects with id, name, and sessionCount. The cURL, JavaScript, and Python examples are equivalent and use the same endpoint and authentication.

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

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

### Check Session with Python

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

Use this Python requests example to send a HEAD request and check if the session exists. Prints the ETag header if the status code is 200.

```python
import requests

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

if response.status_code == 200:
    print('Session exists')
    print('ETag:', response.headers.get('ETag'))
```

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

### Successful response with session data

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

Example of a 200 Success response containing the full session object with metadata, timestamps, and project details.

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

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

### 200 Success Response

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

Example response indicating the session was successfully deleted.

```json
{
  "success": true,
  "data": {
    "success": true
  }
}
```

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

### 401 Unauthorized Response for List Sessions

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

Example error response when the authentication token is invalid or missing.

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

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

### GET /api/v1/projects

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

Retrieves a list of projects for the authenticated user. Requires a valid API key sent as a Bearer token in the Authorization header.

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

### Description
Retrieves a list of projects for the authenticated user.

### Method
GET

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

### Authentication
Bearer token in the Authorization header. Store your API key in the SPECSTORY_API_KEY environment variable.

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

### Response
#### Success Response (200)
Returns a list of projects.

#### Error Responses
- **401 Unauthorized**: Returned when no authentication token is provided or the token is invalid.
  ```json
  {
    "success": false,
    "error": "Invalid session token"
  }
  ```
- **403 Forbidden**: Returned when the authenticated user doesn't have permission for the requested resource.
  ```json
  {
    "success": false,
    "error": "Insufficient permissions"
  }
  ```
```

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

### Make authenticated request using os.getenv in Python

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

Reads the SPECSTORY_API_KEY from the environment using os.getenv and sends a GET request to the projects endpoint with the Authorization and Content-Type headers.

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

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

### GET /api/v1/projects

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

Retrieves all projects in the user's workspace. Requires a Bearer token for authentication. The response includes an array of project objects and a total count.

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

### Description
Retrieve all projects in your workspace.

### Method
GET

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

### Parameters
#### Headers
- **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 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 Unauthorized)
- **success** (boolean) - Indicates if the request was successful
- **error** (string) - Error message describing the authentication failure

#### Error Response Example
```json
{
  "success": false,
  "error": "Invalid or missing authentication token"
}
```
```

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

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

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

Fetches a session by its project and session IDs. Returns the session's markdown content, metadata, and related project details.

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

### Description
Fetches a session by its project and session IDs. Returns the session's markdown content, metadata, and related project details.

### Method
GET

### Endpoint
https://cloud.specstory.com/api/v1/projects/{projectId}/sessions/{sessionId}

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The ID of the project that owns the session.
- **sessionId** (string) - Required - The unique ID of the session to retrieve.

### Request Example
None required - this is a GET request with no body.

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

#### Response Example
{
  "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** (boolean) - false
- **error** (string) - "Session not found"
```

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

### Get Project with Sessions (GraphQL Query and Variables)

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

Retrieves a specific project and its most recent sessions (up to 10) with metadata. Requires a project ID variable. The variables JSON is provided to pass as input.

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

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

### Update Project - 403 Forbidden Response

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

Example error response when the user lacks permission to update the project.

```json
{
  "success": false,
  "error": "You do not have permission to update this project"
}
```

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

### GET /api/v1/projects

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

This endpoint is referenced in the error documentation as a way to list available projects, which helps users verify project IDs and access.

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

### Description
Lists available projects. This endpoint is referenced in the error documentation as a way to verify project IDs and access.

### Method
GET

### Endpoint
/api/v1/projects

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **error** (string) - Error message if the request failed.

#### Response Example
{
  "success": false,
  "error": "Project not found"
}
```

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

### cURL request to get a session

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

Use this cURL command to retrieve a session. Replace YOUR_API_KEY with your actual API key and the session ID in the URL.

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

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

### Handle GraphQL Errors

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

Example of the standard GraphQL error response structure containing a 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"
      }
    }
  ]
}
```

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

### Send GraphQL query to /api/v1/graphql

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

Example requests to the GraphQL endpoint using cURL, JavaScript fetch, and Python requests. All use the same query and variables to search sessions. Requires a valid Bearer token.

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query SearchSessions($query: String!) { searchSessions(query: $query, limit: 10) { total results { id name rank } } }",
    "variables": {"query": "authentication bug fix"}
  }' \
  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 SearchSessions($query: String!) {
        searchSessions(query: $query, limit: 10) {
          total
          results {
            id
            name
            rank
          }
        }
      }
    `,
    variables: {
      query: 'authentication bug fix'
    }
  })
});

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

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

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

### CI/CD pipeline step for AIrgap with JSON output

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

A GitHub Actions/CI step that runs 'airgap' with the base ref and JSON output format to validate code changes. The output is shown as an example JSON failure response.

```yaml
- name: Validate Code Changes
  run: |
    airgap --base ${{ github.base_ref }} --json
```

```json
{
  "status": "fail",
  "violations": [
    {
      "file": "src/auth/login.js",
      "rule": "!src/auth/**",
      "reason": "Protected file modified"
    }
  ]
}
```

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

### 400 Bad Request - Missing Required Fields Error Response

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

Example error response for a 400 Bad Request when a required parameter is missing or has an incorrect name.

```json
{
  "success": false,
  "error": "Missing required field: name"
}
```

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

### GraphQL Query with Variables (cURL, JavaScript)

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

Use GraphQL variables to make queries reusable. The query GetProject takes a $projectId variable and fetches the project with its first 5 sessions. The cURL and JavaScript examples are equivalent.

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

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

### Test Authentication with curl to List Projects

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

Sends a GET request to the SpecStory Cloud API with a Bearer token to list projects. A successful response returns JSON with a success flag, data object, and total project count. Use this to verify your API key works.

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

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

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

### cURL Request to List Sessions

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

Sends a GET request to the List Sessions endpoint with a Bearer token. Replace YOUR_API_KEY with your actual API key and proj_abc123 with your project ID.

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

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

### List Projects API Responses (200 Success, 401 Unauthorized)

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

Example responses for the List Projects endpoint. The 200 Success response includes an array of project objects with fields like id, ownerId, name, icon, color, createdAt, and updatedAt, plus a total count. The 401 Unauthorized response indicates an invalid or missing authentication token.

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

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

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

### Delete Project Request Examples

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

Send a DELETE request to the /api/v1/projects/{projectId} endpoint to permanently delete a project. Requires a Bearer token in the Authorization header. The projectId is specified in the URL path.

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

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

### Start Claude Code with auto-save

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

Launch Claude Code through SpecStory to automatically collect a Markdown transcript in `.specstory/history/`. While active, all Claude Code features work, and both sides of the chat plus terminal output from `!` commands are recorded.

```bash
specstory run claude
```

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

### CLI commands for authentication and syncing sessions

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

Run `specstory login` once per machine to authenticate. Use `specstory sync` to upload all local sessions in the current repo, or `specstory sync -u <session-uuid>` to sync a single session by ID.

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

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

### Run Mintlify Dev Server

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

Runs the Mintlify development server at the root of the documentation folder (where mint.json is).

```bash
mintlify dev
```

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

### Run Gemini CLI with Auto-save

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

Launches Gemini CLI through SpecStory to capture a Markdown history in .specstory/history/.

```bash
specstory run gemini
```
Tokens:
Raw