Skip to main content

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.

A Python client library for the pre.dev Architect API. Generate comprehensive software specifications using AI-powered analysis.

​
Features

  • 🚀 Fast Spec: Generate comprehensive specifications quickly - perfect for MVPs and prototypes
  • 🔍 Deep Spec: Generate ultra-detailed specifications for complex systems with enterprise-grade depth
  • ⚡ Async Spec: Non-blocking async methods for long-running requests
  • 📊 Status Tracking: Check the status of async specification generation requests
  • 🔎 List & Search: Discover, filter, and search through your specification history
  • 💳 Credits Management: Check your remaining prototype credits balance
  • ✨ Type Hints: Full type annotations for better IDE support
  • 🛡️ Error Handling: Custom exceptions for different error scenarios

​
Installation

Install the pre.dev Python SDK using pip: 
pip install predev-api

​
Quick Start

from predev_api import PredevAPI

# Initialize the predev client with your API key
predev = PredevAPI(api_key="your_api_key_here")

# Generate a fast specification
result = predev.fast_spec(
    input_text="Build a task management app with team collaboration"
)

print(result)

​
Authentication

The pre.dev API uses API key authentication. Get your API key from the pre.dev dashboard under Settings → API Keys: 
predev = PredevAPI(api_key="your_api_key")

​
API Methods

​
Synchronous Methods

​
Fast Spec Generation

Generate a fast specification (30-40 seconds, ~5-10 credits). 
result = predev.fast_spec(
    input_text="Build a SaaS project management tool with real-time collaboration",
    current_context=None,  # Optional: existing project context
    doc_urls=None  # Optional: documentation URLs to reference
)
Parameters:
  • input_text (required): str - Description of what you want to build
  • current_context (optional): str - Existing project context
  • doc_urls (optional): List[str] - Documentation URLs to reference
Returns: SpecResponse object with complete specification data Example: 
result = predev.fast_spec(
    input_text="Build a SaaS project management tool with real-time collaboration"
)

​
Deep Spec Generation

Generate a deep specification (2-3 minutes, ~10-50 credits). 
result = predev.deep_spec(
    input_text="Build a healthcare platform with HIPAA compliance",
    current_context=None,  # Optional: existing project context
    doc_urls=None  # Optional: documentation URLs
)
Parameters: Same as fast_spec Returns: SpecResponse object with comprehensive specification data Example: 
result = predev.deep_spec(
    input_text="Build a healthcare platform with HIPAA compliance"
)

​
Asynchronous Methods

​
Fast Spec Async

Generate a fast specification asynchronously (returns immediately). 
result = predev.fast_spec_async(
    input_text="Build a comprehensive e-commerce platform"
)
# Returns: AsyncResponse(specId="spec_123", status="pending")
Parameters: Same as fast_spec Returns: AsyncResponse object with specId for polling

​
Deep Spec Async

Generate a deep specification asynchronously (returns immediately). 
result = predev.deep_spec_async(
    input_text="Build a fintech platform with regulatory compliance"
)
# Returns: AsyncResponse(specId="spec_456", status="pending")
Parameters: Same as fast_spec Returns: AsyncResponse object with specId for polling

​
Status Checking

​
Get Spec Status

Check the status of an async specification generation request. 
status = predev.get_spec_status("spec_123")
# Returns SpecResponse with status: "pending" | "processing" | "completed" | "failed"
Parameters:
  • spec_id (required): str - The specification ID from async methods
Returns: SpecResponse object with current status and data (when completed) Example: 
status = predev.get_spec_status("spec_123")
# Returns SpecResponse with status: "pending" | "processing" | "completed" | "failed"

​
Credits Management

​
Get Credits Balance

Get the remaining prototype credits balance for your API key. 
balance = predev.get_credits_balance()
# Returns: CreditsBalanceResponse(success=True, creditsRemaining=450)
Parameters: None Returns: CreditsBalanceResponse object with credits remaining Example: 
balance = predev.get_credits_balance()
if balance.creditsRemaining < 50:
    print(f"Low credits: {balance.creditsRemaining} remaining")
else:
    print(f"Credits available: {balance.creditsRemaining}")

​
Listing and Searching Specs

​
List Specifications

List all specs with optional filtering and pagination. 
# Get first 20 specs
result = predev.list_specs()

# Get completed specs only
completed = predev.list_specs(status='completed')

# Paginate: get specs 20-40
page2 = predev.list_specs(skip=20, limit=20)

# Filter by endpoint type
fast_specs = predev.list_specs(endpoint='fast_spec')
Parameters:
  • limit (optional): int - Results per page (1-100, default: 20)
  • skip (optional): int - Offset for pagination (default: 0)
  • endpoint (optional): "fast_spec" | "deep_spec" - Filter by endpoint type
  • status (optional): "pending" | "processing" | "completed" | "failed" - Filter by status
Returns: ListSpecsResponse object with specs array and pagination metadata

​
Search Specifications

Search for specs using regex patterns (case-insensitive). 
# Search for "payment" specs
payment_specs = predev.find_specs(query='payment')

# Search for specs starting with "Build"
build_specs = predev.find_specs(query='^Build')

# Search: only completed specs mentioning "auth"
auth_specs = predev.find_specs(
    query='auth',
    status='completed'
)

# Complex regex: find SaaS or SASS projects
saas_specs = predev.find_specs(query='saas|sass')
Parameters:
  • query (required): str - Regex pattern (case-insensitive)
  • limit (optional): int - Results per page (1-100, default: 20)
  • skip (optional): int - Offset for pagination (default: 0)
  • endpoint (optional): "fast_spec" | "deep_spec" - Filter by endpoint type
  • status (optional): "pending" | "processing" | "completed" | "failed" - Filter by status
Returns: ListSpecsResponse object with matching specs and pagination metadata Regex Pattern Examples:
PatternMatches
payment”payment”, “Payment”, “make payment”
^BuildSpecs starting with “Build”
platform$Specs ending with “platform”
(API|REST)Either “API” or “REST”
auth.*system”auth” then anything then “system”
\\d{3,}3+ digits (budgets, quantities)
saas|sassSaaS or SASS

​
File Upload Support

All fast_spec, deep_spec, fast_spec_async, and deep_spec_async methods support optional file uploads. This allows you to provide architecture documents, requirements files, design mockups, RFPs (Request for Proposals), or other context files to improve specification generation.

​
Using File Path (Simplest)

from predev_api import PredevAPI

predev = PredevAPI(api_key="your_api_key")

# Just pass the file path as a string
result = predev.fast_spec(
    input_text="Generate specs based on these requirements",
    file="path/to/requirements.pdf"
)

​
Using File-like Objects

# Open and upload a file
with open("architecture.doc", "rb") as f:
    result = predev.deep_spec(
        input_text="Create comprehensive specs",
        file=f
    )

# Or pass a file-like object
from io import BytesIO

file_content = BytesIO(b"Design specifications...")
result = predev.fast_spec(
    input_text="Generate specs",
    file=file_content
)

​
Supported File Types

  • PDF documents (*.pdf)
  • Word documents (*.doc, *.docx)
  • Text files (*.txt)
  • Images (*.jpg, *.png, *.jpeg)

​
Response with File Upload

When you upload a file, the response includes: 
result = predev.fast_spec(
    input_text="Based on the design document",
    file="design.pdf"
)

print(result.uploadedFileName)       # "design.pdf"
print(result.uploadedFileShortUrl)   # "https://api.pre.dev/f/xyz123"
print(result.codingAgentSpecUrl)     # Spec for AI systems
print(result.humanSpecUrl)           # Spec for humans

​
Response Types

​
AsyncResponse

@dataclass
class AsyncResponse:
    specId: str                                    # Unique ID for polling (e.g., "spec_abc123")
    status: Literal['pending', 'processing', 'completed', 'failed']

​
SpecResponse

@dataclass
class SpecResponse:
    # Basic info
    _id: Optional[str] = None                      # Internal ID
    created: Optional[str] = None                  # ISO timestamp
    endpoint: Optional[Literal['fast_spec', 'deep_spec']] = None
    input: Optional[str] = None                    # Original input text
    status: Optional[Literal['pending', 'processing', 'completed', 'failed']] = None
    success: Optional[bool] = None

    # Output data (when completed)
    uploadedFileShortUrl: Optional[str] = None    # URL to input file
    uploadedFileName: Optional[str] = None        # Name of input file
    humanSpecUrl: Optional[str] = None            # URL to human-readable spec
    humanSpecMarkdown: Optional[str] = None       # Full markdown SOW for humans/clients
    humanSpecJson: Optional['HumanSpecJson'] = None   # Full structured SOW JSON
    totalHumanHours: Optional[float] = None       # Estimated hours for human implementation
    codingAgentSpecUrl: Optional[str] = None          # URL to coding agent spec format
    codingAgentSpecMarkdown: Optional[str] = None     # Simplified markdown SOW for AI tools
    codingAgentSpecJson: Optional['CodingAgentSpecJson'] = None  # Structured SOW JSON for AI tools
    executionTime: Optional[int] = None           # Processing time in milliseconds

    # Integration URLs (when completed)
    predevUrl: Optional[str] = None               # Link to pre.dev project

    # Error handling
    errorMessage: Optional[str] = None            # Error details if failed
    progress: Optional[int] = None                # Overall progress percentage (0-100)
    progressMessage: Optional[str] = None         # Detailed progress message (e.g., "Generating User Stories...")


@dataclass
class CodingAgentSpecJson:
    title: Optional[str] = None
    executiveSummary: Optional[str] = None
    coreFunctionalities: Optional[List['SpecCoreFunctionality']] = None
    techStack: Optional[List['SpecTechStackItem']] = None
    techStackGrouped: Optional[dict] = None
    milestones: Optional[List['CodingAgentMilestone']] = None


@dataclass
class CodingAgentMilestone:
    milestoneNumber: int = 0
    description: str = ''
    stories: List['CodingAgentStory'] = None


@dataclass
class CodingAgentStory:
    id: Optional[str] = None
    title: str = ''
    description: Optional[str] = None
    acceptanceCriteria: Optional[List[str]] = None
    complexity: Optional[str] = None
    subTasks: List['CodingAgentSubTask'] = None


@dataclass
class CodingAgentSubTask:
    id: Optional[str] = None
    description: str = ''
    complexity: str = ''


@dataclass
class HumanSpecJson:
    title: Optional[str] = None
    executiveSummary: Optional[str] = None
    coreFunctionalities: Optional[List['SpecCoreFunctionality']] = None
    personas: Optional[List['SpecPersona']] = None
    techStack: Optional[List['SpecTechStackItem']] = None
    techStackGrouped: Optional[dict] = None
    milestones: Optional[List['HumanSpecMilestone']] = None
    totalHours: Optional[float] = None
    roles: Optional[List['SpecRole']] = None


@dataclass
class HumanSpecMilestone:
    milestoneNumber: int = 0
    description: str = ''
    hours: float = 0.0
    stories: List['HumanSpecStory'] = None


@dataclass
class HumanSpecStory:
    id: Optional[str] = None
    title: str = ''
    description: Optional[str] = None
    acceptanceCriteria: Optional[List[str]] = None
    hours: float = 0.0
    complexity: Optional[str] = None
    subTasks: List['HumanSpecSubTask'] = None


@dataclass
class HumanSpecSubTask:
    id: Optional[str] = None
    description: str = ''
    hours: float = 0.0
    complexity: str = ''
    roles: Optional[List['SpecRole']] = None


@dataclass
class SpecPersona:
    title: str = ''
    description: str = ''
    primaryGoals: Optional[List[str]] = None
    painPoints: Optional[List[str]] = None
    keyTasks: Optional[List[str]] = None


@dataclass
class SpecRole:
    name: str = ''
    shortHand: str = ''


@dataclass
class SpecCoreFunctionality:
    name: str = ''
    description: str = ''
    priority: Optional[str] = None  # "High" | "Medium" | "Low"


@dataclass
class SpecTechStackItem:
    name: str = ''
    category: str = ''

​
ListSpecsResponse

@dataclass
class ListSpecsResponse:
    specs: List[SpecResponse]  # Array of spec objects
    total: int                 # Total count of matching specs
    hasMore: bool              # Whether more results are available

​
CreditsBalanceResponse

@dataclass
class CreditsBalanceResponse:
    success: bool
    creditsRemaining: int

​
Examples

​
Generate Fast Spec

​
Search Specs with Regex

from predev_api import PredevAPI

predev = PredevAPI(api_key="your_api_key")

# Find all payment-related specs
payment_specs = predev.find_specs(query='payment')
print(f"Found {payment_specs.total} payment specs")

# Find specs starting with "Build"
build_specs = predev.find_specs(query='^Build')

# Find completed authentication specs
auth_specs = predev.find_specs(
    query='auth',
    status='completed',
    endpoint='deep_spec'
)

# Complex search: SaaS or SASS projects
saas_specs = predev.find_specs(query='saas|sass')
for spec in saas_specs.specs:
    print(f"Found: {spec.input}")

​
Check Credits Balance

from predev_api import PredevAPI

predev = PredevAPI(api_key="your_api_key")

# Get current credit balance
balance = predev.get_credits_balance()
print(f"Credits remaining: {balance.creditsRemaining}")

# Check before making expensive request
if balance.creditsRemaining >= 50:
    result = predev.deep_spec(
        input_text="Build an enterprise platform"
    )
else:
    print(f"Insufficient credits. Need 50, have {balance.creditsRemaining}")

​
Error Handling