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

# GET /list-specs

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": "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`             | 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?: 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="/api-reference/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: string
          description: Human-readable progress description
        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)
    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/playground (Solo) or
        https://pre.dev/enterprise/dashboard?page=api (Enterprise). Use format:
        Bearer YOUR_API_KEY
      x-default: YOUR_API_KEY

````