> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pre.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List Specs

> List all specs with pagination and filtering. Perfect for displaying user spec history, recent specs, or filtered views.

List all specifications with support for pagination and filtering by status or endpoint type.

## Overview

* **Cost:** Free (no credits required)
* **Use Cases:** Display spec history, build dashboards, monitor spec status
* **Response Time:** Instant
* **Returns:** Paginated array of specs with metadata

## Endpoint

```
GET https://api.pre.dev/list-specs
```

## Headers

```
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

| Parameter  | Type    | Required | Default | Description                                                         |
| ---------- | ------- | -------- | ------- | ------------------------------------------------------------------- |
| `limit`    | integer | ❌        | 20      | Results per page (1-100)                                            |
| `skip`     | integer | ❌        | 0       | Number of records to skip for pagination                            |
| `endpoint` | string  | ❌        | -       | Filter by endpoint: `fast_spec` or `deep_spec`                      |
| `status`   | string  | ❌        | -       | Filter by status: `pending`, `processing`, `completed`, or `failed` |

### Parameter Details

**limit**

* Minimum: 1
* Maximum: 100
* Default: 20
* Controls how many specs are returned per request

**skip**

* Minimum: 0
* Used for pagination (e.g., skip=20 for page 2 with limit=20)

**endpoint**

* `fast_spec` - Only show Fast Spec generations
* `deep_spec` - Only show Deep Spec generations

**status**

* `pending` - Queued but not started
* `processing` - Currently generating
* `completed` - Successfully finished
* `failed` - Generation failed

## Response

### Success Response

```json theme={null}
{
  "specs": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "created": "2024-01-15T14:30:00.000Z",
      "endpoint": "fast_spec",
      "input": "Build a SaaS project management tool with team collaboration",
      "status": "completed",
      "success": true,
      "humanSpecUrl": "https://api.pre.dev/s/a6hFJRV6",
      "totalHumanHours": 120,
      "codingAgentSpecUrl": "https://api.pre.dev/s/a6hFJRV7",
      "executionTime": 38500,
      "predevUrl": "https://pre.dev/projects/abc123",
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "created": "2024-01-15T12:15:00.000Z",
      "endpoint": "deep_spec",
      "input": "Build an enterprise healthcare platform with HIPAA compliance",
      "status": "processing",
      "success": false,
      "progress": 45,
      "progressMessage": "Generating architecture recommendations..."
    }
  ],
  "total": 42,
  "hasMore": true
}
```

### Response Fields

| Field     | Type    | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `specs`   | array   | Array of spec objects (see Spec Object below) |
| `total`   | integer | Total number of specs matching the filters    |
| `hasMore` | boolean | Whether more pages are available              |

### Spec Object Fields

| Field                  | Type    | Always Present | Description                                                              |
| ---------------------- | ------- | -------------- | ------------------------------------------------------------------------ |
| `_id`                  | string  | ✅              | Unique spec identifier                                                   |
| `created`              | string  | ✅              | ISO 8601 timestamp of creation                                           |
| `endpoint`             | string  | ✅              | `"fast_spec"` or `"deep_spec"`                                           |
| `input`                | string  | ✅              | Original input text                                                      |
| `status`               | string  | ✅              | Current status                                                           |
| `success`              | boolean | ✅              | Whether generation succeeded                                             |
| `uploadedFileShortUrl` | string  | ❌              | URL if file was uploaded                                                 |
| `uploadedFileName`     | string  | ❌              | Name of uploaded file                                                    |
| `humanSpecUrl`         | string  | ❌              | Human-readable spec URL (when completed)                                 |
| `totalHumanHours`      | number  | ❌              | Estimated total hours for a human to implement the spec (when completed) |
| `codingAgentSpecUrl`   | string  | ❌              | Coding agent spec URL (when completed)                                   |
| `executionTime`        | number  | ❌              | Processing time in ms (when completed)                                   |
| `predevUrl`            | string  | ❌              | pre.dev project URL (when completed)                                     |
| `errorMessage`         | string  | ❌              | Error details (when failed)                                              |
| `progress`             | number  | ❌              | Completion percentage 0-100 (when processing)                            |
| `progressMessage`      | string  | ❌              | Status message (when processing)                                         |

## Code Examples

### cURL Examples

**Get first 20 specs:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pre.dev/list-specs"
```

**Get completed specs only:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pre.dev/list-specs?status=completed"
```

**Paginate through results:**

```bash theme={null}
# Page 1 (specs 0-19)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pre.dev/list-specs?limit=20&skip=0"

# Page 2 (specs 20-39)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pre.dev/list-specs?limit=20&skip=20"

# Page 3 (specs 40-59)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pre.dev/list-specs?limit=20&skip=40"
```

**Get all deep specs:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pre.dev/list-specs?endpoint=deep_spec"
```

**Get failed specs for debugging:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pre.dev/list-specs?status=failed&limit=100"
```

**Combine filters:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pre.dev/list-specs?endpoint=fast_spec&status=completed&limit=50"
```

### JavaScript/Node.js

```javascript theme={null}
async function listSpecs(options = {}) {
  const {
    limit = 20,
    skip = 0,
    endpoint = null,
    status = null
  } = options;

  const params = new URLSearchParams({
    limit: limit.toString(),
    skip: skip.toString()
  });

  if (endpoint) params.append('endpoint', endpoint);
  if (status) params.append('status', status);

  const response = await fetch(
    `https://api.pre.dev/list-specs?${params}`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage examples

// Get recent specs
const recent = await listSpecs({ limit: 5 });
console.log(`Showing ${recent.specs.length} of ${recent.total} specs`);

// Get completed specs only
const completed = await listSpecs({ status: 'completed' });

// Paginate through all specs
async function getAllSpecs() {
  let allSpecs = [];
  let skip = 0;
  const limit = 50;

  while (true) {
    const response = await listSpecs({ skip, limit });
    allSpecs.push(...response.specs);
    
    if (!response.hasMore) break;
    skip += limit;
  }

  return allSpecs;
}

// Build pagination UI
async function loadPage(pageNumber, pageSize = 20) {
  const skip = pageNumber * pageSize;
  const data = await listSpecs({ skip, limit: pageSize });
  
  return {
    specs: data.specs,
    currentPage: pageNumber,
    totalPages: Math.ceil(data.total / pageSize),
    hasNext: data.hasMore
  };
}
```

### TypeScript

```typescript theme={null}
interface ListSpecsOptions {
  limit?: number;
  skip?: number;
  endpoint?: 'fast_spec' | 'deep_spec';
  status?: 'pending' | 'processing' | 'completed' | 'failed';
}

interface SpecObject {
  _id: string;
  created: string;
  endpoint: 'fast_spec' | 'deep_spec';
  input: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  success: boolean;
  uploadedFileShortUrl?: string;
  uploadedFileName?: string;
  humanSpecUrl?: string;
  codingAgentSpecUrl?: string;
  executionTime?: number;
  predevUrl?: string;
  errorMessage?: string;
  progress?: number;
  progressMessage?: string;
}

interface ListSpecsResponse {
  specs: SpecObject[];
  total: number;
  hasMore: boolean;
}

class SpecClient {
  constructor(private apiKey: string) {}

  async listSpecs(options: ListSpecsOptions = {}): Promise<ListSpecsResponse> {
    const {
      limit = 20,
      skip = 0,
      endpoint,
      status
    } = options;

    const params = new URLSearchParams({
      limit: limit.toString(),
      skip: skip.toString()
    });

    if (endpoint) params.append('endpoint', endpoint);
    if (status) params.append('status', status);

    const response = await fetch(
      `https://api.pre.dev/list-specs?${params}`,
      {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      }
    );

    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }

    return response.json();
  }

  async *paginateSpecs(
    options: ListSpecsOptions = {}
  ): AsyncGenerator<SpecObject[], void, unknown> {
    let skip = 0;
    const limit = options.limit || 20;

    while (true) {
      const response = await this.listSpecs({ ...options, skip, limit });
      yield response.specs;
      
      if (!response.hasMore) break;
      skip += limit;
    }
  }
}

// Usage
const client = new SpecClient('YOUR_API_KEY');

// Simple list
const response = await client.listSpecs({ status: 'completed' });
console.log(`Found ${response.total} completed specs`);

// Pagination generator
for await (const specsPage of client.paginateSpecs({ limit: 50 })) {
  console.log(`Processing ${specsPage.length} specs...`);
  specsPage.forEach(spec => {
    console.log(`- ${spec.input.substring(0, 50)}...`);
  });
}
```

### Python

```python theme={null}
import requests
from typing import Optional, List, Dict, Any, Generator

class SpecClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'https://api.pre.dev'
    
    def list_specs(
        self,
        limit: int = 20,
        skip: int = 0,
        endpoint: Optional[str] = None,
        status: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        List specs with optional filtering and pagination.
        
        Args:
            limit: Number of results per page (1-100)
            skip: Number of records to skip
            endpoint: Filter by 'fast_spec' or 'deep_spec'
            status: Filter by 'pending', 'processing', 'completed', or 'failed'
        
        Returns:
            Dictionary with 'specs' array, 'total' count, and 'hasMore' flag
        """
        params = {'limit': limit, 'skip': skip}
        if endpoint:
            params['endpoint'] = endpoint
        if status:
            params['status'] = status
        
        response = requests.get(
            f'{self.base_url}/list-specs',
            params=params,
            headers={'Authorization': f'Bearer {self.api_key}'}
        )
        response.raise_for_status()
        return response.json()
    
    def get_all_specs(
        self,
        endpoint: Optional[str] = None,
        status: Optional[str] = None,
        batch_size: int = 50
    ) -> List[Dict[str, Any]]:
        """Fetch all specs matching the filters."""
        all_specs = []
        skip = 0
        
        while True:
            response = self.list_specs(
                limit=batch_size,
                skip=skip,
                endpoint=endpoint,
                status=status
            )
            all_specs.extend(response['specs'])
            
            if not response['hasMore']:
                break
            
            skip += batch_size
        
        return all_specs
    
    def paginate_specs(
        self,
        endpoint: Optional[str] = None,
        status: Optional[str] = None,
        batch_size: int = 50
    ) -> Generator[List[Dict[str, Any]], None, None]:
        """Generator that yields batches of specs."""
        skip = 0
        
        while True:
            response = self.list_specs(
                limit=batch_size,
                skip=skip,
                endpoint=endpoint,
                status=status
            )
            
            if not response['specs']:
                break
            
            yield response['specs']
            
            if not response['hasMore']:
                break
            
            skip += batch_size

# Usage examples
client = SpecClient('YOUR_API_KEY')

# Get recent specs
recent = client.list_specs(limit=5)
print(f"Showing {len(recent['specs'])} of {recent['total']} specs")

# Get all completed specs
completed_specs = client.get_all_specs(status='completed')
print(f"Found {len(completed_specs)} completed specs")

# Process specs in batches
for batch in client.paginate_specs(status='completed', batch_size=25):
    print(f"Processing batch of {len(batch)} specs")
    for spec in batch:
        print(f"  - {spec['input'][:50]}...")

# Filter by endpoint and status
fast_completed = client.list_specs(
    endpoint='fast_spec',
    status='completed',
    limit=100
)

# Build pagination for UI
def get_page(page_number: int, page_size: int = 20):
    skip = page_number * page_size
    response = client.list_specs(skip=skip, limit=page_size)
    
    return {
        'specs': response['specs'],
        'current_page': page_number,
        'total_pages': (response['total'] + page_size - 1) // page_size,
        'has_next': response['hasMore']
    }

# Display page 3
page_data = get_page(2, page_size=20)
print(f"Page {page_data['current_page'] + 1} of {page_data['total_pages']}")
```

## Common Use Cases

### 1. Display Recent Specs Dashboard

```javascript theme={null}
async function getRecentSpecsForDashboard() {
  const response = await fetch(
    'https://api.pre.dev/list-specs?limit=10',
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const data = await response.json();
  
  return data.specs.map(spec => ({
    id: spec._id,
    title: spec.input.substring(0, 80) + '...',
    type: spec.endpoint === 'fast_spec' ? 'Fast' : 'Deep',
    status: spec.status,
    createdAt: new Date(spec.created),
    url: spec.humanSpecUrl
  }));
}
```

### 2. Monitor Failed Specs

```python theme={null}
def check_failed_specs(client):
    """Check for failed specs in the last 24 hours."""
    failed = client.list_specs(status='failed', limit=100)
    
    recent_failures = []
    for spec in failed['specs']:
        created = datetime.fromisoformat(spec['created'].replace('Z', '+00:00'))
        if datetime.now(timezone.utc) - created < timedelta(hours=24):
            recent_failures.append({
                'id': spec['_id'],
                'input': spec['input'],
                'error': spec.get('errorMessage', 'Unknown error'),
                'created': created
            })
    
    return recent_failures
```

### 3. Export Completed Specs

```javascript theme={null}
async function exportCompletedSpecs() {
  const allCompleted = [];
  let skip = 0;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://api.pre.dev/list-specs?status=completed&skip=${skip}&limit=${limit}`,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    );
    const data = await response.json();
    
    allCompleted.push(...data.specs);
    
    if (!data.hasMore) break;
    skip += limit;
  }

  return allCompleted;
}
```

### 4. Build Pagination Component

```typescript theme={null}
interface PaginationState {
  currentPage: number;
  pageSize: number;
  totalItems: number;
  items: SpecObject[];
}

async function loadPage(
  pageNumber: number,
  pageSize: number,
  filters?: ListSpecsOptions
): Promise<PaginationState> {
  const client = new SpecClient('YOUR_API_KEY');
  const response = await client.listSpecs({
    ...filters,
    skip: pageNumber * pageSize,
    limit: pageSize
  });

  return {
    currentPage: pageNumber,
    pageSize,
    totalItems: response.total,
    items: response.specs
  };
}
```

## Best Practices

### Pagination

* Use reasonable page sizes (20-50 specs)
* Cache results when appropriate
* Show loading states while fetching

### Filtering

* Combine filters to reduce result sets
* Use `status=completed` for user-facing spec lists
* Use `status=failed` for debugging/monitoring

### Performance

* Don't fetch all specs at once if you have many
* Use pagination for large datasets
* Consider implementing infinite scroll with `skip` parameter

### Error Handling

* Always check response status codes
* Handle empty result sets gracefully
* Show appropriate messages when no specs match filters

<Card title="Next: Find Specs (Search)" icon="arrow-right" href="/architect-agent/api/find-specs">
  Search specs using regex patterns for advanced filtering.
</Card>


## OpenAPI

````yaml GET /list-specs
openapi: 3.1.0
info:
  title: pre.dev Architect API
  description: >-
    Generate comprehensive software specifications for coding agents. The
    Architect API helps you create detailed project specifications that AI
    coding agents can understand and implement.
  version: 1.1.0
  contact:
    name: pre.dev Support
    url: https://pre.dev
    email: support@pre.dev
  license:
    name: Proprietary
    url: https://pre.dev/terms
servers:
  - url: https://api.pre.dev
    description: Production API Server
security:
  - apiKeyAuth: []
tags:
  - name: Spec Generation
    description: Generate comprehensive software specifications for AI coding agents
  - name: Status
    description: Check status of asynchronous specification processing
  - name: Spec Management
    description: List and search existing specifications
  - name: Account
    description: Manage user account and credits
  - name: Batches
    description: Submit and retrieve browser-agent task batches
paths:
  /list-specs:
    get:
      tags:
        - Spec Management
      summary: List Specs
      description: >-
        List all specifications with pagination and filtering. Perfect for
        displaying user spec history, recent specs, or filtered views. This
        endpoint is free and does not consume credits.
      operationId: listSpecs
      parameters:
        - name: limit
          in: query
          required: false
          description: Number of results per page (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
        - name: skip
          in: query
          required: false
          description: Number of records to skip for pagination
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 0
        - name: endpoint
          in: query
          required: false
          description: Filter by endpoint type
          schema:
            type: string
            enum:
              - fast_spec
              - deep_spec
            example: fast_spec
        - name: status
          in: query
          required: false
          description: Filter by processing status
          schema:
            type: string
            enum:
              - pending
              - processing
              - completed
              - failed
            example: completed
      responses:
        '200':
          description: Specs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSpecsResponse'
              examples:
                recentSpecs:
                  summary: Recent Specs
                  value:
                    specs:
                      - _id: 507f1f77bcf86cd799439011
                        created: '2024-01-15T14:30:00.000Z'
                        endpoint: fast_spec
                        input: >-
                          Build a SaaS project management tool with team
                          collaboration
                        status: completed
                        success: true
                        humanSpecUrl: https://api.pre.dev/s/a6hFJRV6
                        codingAgentSpecUrl: https://api.pre.dev/s/a6hFJRV7
                        executionTime: 38500
                    total: 42
                    hasMore: true
                filteredSpecs:
                  summary: Completed Fast Specs
                  value:
                    specs:
                      - _id: 507f1f77bcf86cd799439012
                        created: '2024-01-15T12:15:00.000Z'
                        endpoint: fast_spec
                        input: Add real-time notifications
                        status: completed
                        success: true
                        executionTime: 35200
                    total: 15
                    hasMore: false
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    ListSpecsResponse:
      type: object
      required:
        - specs
        - total
        - hasMore
      properties:
        specs:
          type: array
          description: Array of spec objects matching the filters
          items:
            $ref: '#/components/schemas/StatusResponse'
        total:
          type: integer
          description: Total number of specs matching the filters
          example: 42
        hasMore:
          type: boolean
          description: Whether more pages are available
          example: true
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error type or code
        message:
          type: string
          description: Human-readable error message
    StatusResponse:
      type: object
      properties:
        _id:
          type: string
          description: MongoDB ObjectId of the spec request
        created:
          type: string
          format: date-time
          description: ISO timestamp when the request was created
        endpoint:
          type: string
          enum:
            - fast_spec
            - deep_spec
          description: Which endpoint was used
        input:
          type: string
          description: Original input text provided
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Current status
        success:
          type: boolean
          description: Whether the request succeeded
        uploadedFileShortUrl:
          type: string
          description: Short URL for uploaded file (if file was uploaded)
        uploadedFileName:
          type: string
          description: Name of uploaded file (if file was uploaded)
        humanSpecUrl:
          type: string
          format: uri
          description: URL where the human-readable spec is hosted (only when completed)
        totalHumanHours:
          type: number
          description: >-
            Estimated total hours for a human to implement the spec (only when
            completed)
        architectureInfographicUrl:
          type: string
          format: uri
          description: >-
            URL to a visual architecture infographic/diagram for the
            specification (only when completed)
        codingAgentSpecUrl:
          type: string
          format: uri
          description: >-
            URL where the coding agent spec format is hosted (only when
            completed)
        codingAgentSpecJson:
          $ref: '#/components/schemas/CodingAgentSpecJson'
          description: >-
            Structured JSON spec optimized for AI coding assistants (only when
            completed)
        codingAgentSpecMarkdown:
          type: string
          description: >-
            Markdown spec optimized for AI coding assistants (only when
            completed)
        humanSpecJson:
          $ref: '#/components/schemas/HumanSpecJson'
          description: >-
            Full structured JSON spec with hours, personas, and roles (only when
            completed)
        humanSpecMarkdown:
          type: string
          description: >-
            Full markdown spec with all details for human review (only when
            completed)
        executionTime:
          type: integer
          description: Processing time in milliseconds (only when completed or failed)
        predevUrl:
          type: string
          format: uri
          description: pre.dev project URL (only when completed)
        zippedDocsUrls:
          type: array
          description: >-
            Array of scraped documentation archives (only when completed). Empty
            array if no docURLs provided or scraping fails
          items:
            $ref: '#/components/schemas/ZippedDocsUrl'
        errorMessage:
          type: string
          description: Error description (only when failed)
        progress:
          type: number
          description: Completion percentage (0-100) while processing
        creditsUsed:
          type: number
          description: >-
            Total credits consumed by this spec generation. Available in
            real-time during processing and persisted on completion. Typical
            values: Fast spec ~5-10, Deep spec ~10-50.
        userFlowGraph:
          $ref: '#/components/schemas/SpecGraph'
          description: >-
            User flow graph with nodes representing user stories/flows and edges
            showing navigation paths (only when completed)
        architectureGraph:
          $ref: '#/components/schemas/SpecGraph'
          description: >-
            System architecture graph with C1/C2 level nodes and their
            relationships (only when completed)
        enrichedTechStack:
          type: array
          items:
            $ref: '#/components/schemas/SpecEnrichedTechStackItem'
          description: >-
            Enriched tech stack with detailed reasons, descriptions, and
            alternatives for each technology (only when completed)
        progressMessage:
          type: string
          description: >-
            Human-readable progress description (e.g. 'Generating
            architecture...')
    CodingAgentSpecJson:
      type: object
      required:
        - executiveSummary
        - coreFunctionalities
        - techStack
        - milestones
      description: >-
        Simplified structured JSON for AI coding tools (excludes hours,
        personas, roles)
      properties:
        title:
          type: string
          description: Title of the specification
        executiveSummary:
          type: string
          description: Executive summary of the project
        coreFunctionalities:
          type: array
          items:
            $ref: '#/components/schemas/SpecCoreFunctionality'
          description: List of core functionalities
        techStack:
          type: array
          items:
            $ref: '#/components/schemas/SpecTechStackItem'
          description: Technology stack items
        techStackGrouped:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Technology stack grouped by category
        milestones:
          type: array
          items:
            $ref: '#/components/schemas/CodingAgentMilestone'
          description: List of milestones
    HumanSpecJson:
      type: object
      required:
        - executiveSummary
        - coreFunctionalities
        - personas
        - techStack
        - milestones
        - totalHours
        - roles
      description: Full structured JSON with hours, personas, and roles for human review
      properties:
        title:
          type: string
          description: Title of the specification
        executiveSummary:
          type: string
          description: Executive summary of the project
        coreFunctionalities:
          type: array
          items:
            $ref: '#/components/schemas/SpecCoreFunctionality'
          description: List of core functionalities
        personas:
          type: array
          items:
            $ref: '#/components/schemas/SpecPersona'
          description: User personas
        techStack:
          type: array
          items:
            $ref: '#/components/schemas/SpecTechStackItem'
          description: Technology stack items
        techStackGrouped:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Technology stack grouped by category
        milestones:
          type: array
          items:
            $ref: '#/components/schemas/HumanSpecMilestone'
          description: List of milestones with hours
        totalHours:
          type: number
          description: Total estimated hours for the project
        roles:
          type: array
          items:
            $ref: '#/components/schemas/SpecRole'
          description: Roles required for the project
    ZippedDocsUrl:
      type: object
      required:
        - platform
        - masterZipShortUrl
      properties:
        platform:
          type: string
          description: >-
            Hostname extracted from the documentation URL (e.g., 'stripe.com',
            'docs.github.com')
          example: stripe.com
        masterZipShortUrl:
          type: string
          format: uri
          description: >-
            Short URL to download the zipped documentation archive for this
            platform
        masterMarkdownShortUrl:
          type: string
          format: uri
          description: Optional short URL to consolidated markdown file for this platform
    SpecGraph:
      type: object
      required:
        - nodes
        - edges
      properties:
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/SpecGraphNode'
          description: Array of graph nodes
        edges:
          type: array
          items:
            $ref: '#/components/schemas/SpecGraphEdge'
          description: Array of graph edges
    SpecEnrichedTechStackItem:
      type: object
      required:
        - name
        - useFor
        - reason
        - description
      properties:
        name:
          type: string
          description: Name of the technology (e.g., React, PostgreSQL)
        useFor:
          type: string
          description: Category label (e.g., Frontend, Backend, Database)
        reason:
          type: string
          description: Why this technology was chosen for this specific project
        description:
          type: string
          description: Technical description of what the technology does
        link:
          type: string
          format: uri
          description: Official website or documentation URL
        helpfulLinks:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
                description: URL to helpful resource
              description:
                type: string
                description: Description of the resource
          description: Array of helpful documentation and tutorial links
        alternatives:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the alternative technology
              link:
                type: string
                format: uri
                description: URL of the alternative technology
              description:
                type: string
                description: Description of the alternative
          description: Array of alternative technologies that could be used instead
    SpecCoreFunctionality:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: Name of the core functionality
        description:
          type: string
          description: Description of the functionality
        priority:
          type: string
          enum:
            - High
            - Medium
            - Low
          description: Priority level of the functionality
    SpecTechStackItem:
      type: object
      required:
        - name
        - category
      properties:
        name:
          type: string
          description: Name of the technology
        category:
          type: string
          description: Category of the technology (e.g., Frontend, Backend, Database)
    CodingAgentMilestone:
      type: object
      required:
        - milestoneNumber
        - description
        - stories
      properties:
        milestoneNumber:
          type: integer
          description: Milestone number
        description:
          type: string
          description: Description of the milestone
        stories:
          type: array
          items:
            $ref: '#/components/schemas/CodingAgentStory'
          description: List of user stories in this milestone
    SpecPersona:
      type: object
      required:
        - title
        - description
      properties:
        title:
          type: string
          description: Title of the persona
        description:
          type: string
          description: Description of the persona
        primaryGoals:
          type: array
          items:
            type: string
          description: Primary goals of the persona
        painPoints:
          type: array
          items:
            type: string
          description: Pain points of the persona
        keyTasks:
          type: array
          items:
            type: string
          description: Key tasks of the persona
    HumanSpecMilestone:
      type: object
      required:
        - milestoneNumber
        - description
        - hours
        - stories
      properties:
        milestoneNumber:
          type: integer
          description: Milestone number
        description:
          type: string
          description: Description of the milestone
        hours:
          type: number
          description: Estimated hours for this milestone
        stories:
          type: array
          items:
            $ref: '#/components/schemas/HumanSpecStory'
          description: List of user stories in this milestone
    SpecRole:
      type: object
      required:
        - name
        - shortHand
      properties:
        name:
          type: string
          description: Full name of the role (e.g., Full Stack Developer)
        shortHand:
          type: string
          description: Short abbreviation for the role (e.g., FSD)
    SpecGraphNode:
      type: object
      required:
        - id
        - label
      properties:
        id:
          type: string
          description: Unique identifier for the node
        label:
          type: string
          description: Display label for the node
        type:
          type: string
          description: >-
            Node type category. For architectureGraph: "frontend",
            "api-services", "databases", or "external-services". For
            userFlowGraph: "flow", "role", etc.
        description:
          type: string
          description: Description of the node
        level:
          type: number
          description: >-
            Graph depth level (1, 2, 3...) for userFlowGraph nodes. Not present
            on architectureGraph nodes.
        hours:
          type: number
          description: Estimated hours for this node
    SpecGraphEdge:
      type: object
      required:
        - source
        - target
      properties:
        source:
          type: string
          description: Source node ID
        target:
          type: string
          description: Target node ID
        description:
          type: string
          description: Description of the relationship
        edgeType:
          type: string
          description: Type of edge relationship
    CodingAgentStory:
      type: object
      required:
        - title
        - subTasks
      properties:
        id:
          type: string
          description: Story identifier (e.g., US-001)
        title:
          type: string
          description: Title of the user story
        description:
          type: string
          description: Description of the user story
        acceptanceCriteria:
          type: array
          items:
            type: string
          description: List of acceptance criteria
        complexity:
          type: string
          description: Complexity estimate for the story
        subTasks:
          type: array
          items:
            $ref: '#/components/schemas/CodingAgentSubTask'
          description: List of subtasks for this story
    HumanSpecStory:
      type: object
      required:
        - title
        - hours
        - subTasks
      properties:
        id:
          type: string
          description: Story identifier (e.g., US-001)
        title:
          type: string
          description: Title of the user story
        description:
          type: string
          description: Description of the user story
        acceptanceCriteria:
          type: array
          items:
            type: string
          description: List of acceptance criteria
        hours:
          type: number
          description: Estimated hours for this story
        complexity:
          type: string
          description: Complexity estimate for the story
        subTasks:
          type: array
          items:
            $ref: '#/components/schemas/HumanSpecSubTask'
          description: List of subtasks for this story
    CodingAgentSubTask:
      type: object
      required:
        - description
        - complexity
      properties:
        id:
          type: string
          description: Subtask identifier
        description:
          type: string
          description: Description of the subtask
        complexity:
          type: string
          enum:
            - S
            - M
            - L
            - XL
          description: Complexity estimate
    HumanSpecSubTask:
      type: object
      required:
        - description
        - hours
        - complexity
      properties:
        id:
          type: string
          description: Subtask identifier
        description:
          type: string
          description: Description of the subtask
        hours:
          type: number
          description: Estimated hours for this subtask
        complexity:
          type: string
          description: Complexity estimate
        roles:
          type: array
          items:
            $ref: '#/components/schemas/SpecRole'
          description: Roles assigned to this subtask
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key for authentication. Get your API key from
        https://pre.dev/projects/key (Solo) or
        https://pre.dev/enterprise/dashboard?page=api (Enterprise). Use format:
        Bearer YOUR_API_KEY
      x-default: YOUR_API_KEY

````