POST /deep-spec

Generate an ultra-detailed, comprehensive project specification.

Overview

Cost: 50 credits
Use Cases: Complex systems, enterprise applications, critical projects
Processing Time: ~2-3 minutes (sync) or instant return (async)
Output: Exhaustive analysis, detailed architecture, comprehensive planning

Subscription Required

Deep Spec requires Solo Premium or Enterprise subscription.

Endpoint

POST https://api.pre.dev/deep-spec

Headers

For JSON requests:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

For file upload requests:

Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY

Request Body

Parameters

For JSON requests:

Parameter	Type	Required	Description
`input`	string	✅	Description of what you want to build
`currentContext`	string	❌	CRITICAL: Existing project/codebase context. When provided, generates feature addition spec. When omitted, generates full new project spec with setup, deployment, docs, maintenance
`docURLs`	string[]	❌	Optional: Array of documentation URLs that Architect will reference when generating specifications. Useful for API documentation, design systems, or existing project docs
`async`	boolean	❌	`false` (default) - wait for completion, or `true` - return immediately with requestId for status polling

For file upload requests (multipart/form-data):

Parameter	Type	Required	Description
`file`	File	❌	Optional: File to be parsed as input (e.g., existing code, documentation, requirements). Can be used alone or combined with `input` text
`input`	string	❌	Optional: Additional text description when using file upload. Can be empty string if using only file
`docURLs`	string[]	❌	Optional: Array of documentation URLs that Architect will reference when generating specifications. Useful for API documentation, design systems, or existing project docs
`async`	boolean	❌	`false` (default) - wait for completion, or `true` - return immediately with requestId for status polling

Deep Spec vs Fast Spec

Feature	Fast Spec	Deep Spec
Cost	10 credits	50 credits
Processing Time	30-40 sec	2-3 min
Structure	Milestones → Stories	Milestones → Stories → Subtasks
Detail Level	Comprehensive	Ultra-detailed
Best For	MVPs, prototypes	Enterprise, complex systems
Feature Analysis	✅	✅✅✅
Architecture Depth	✅	✅✅✅
Risk Analysis	✅	✅✅✅
User Stories	✅	✅✅✅

Example Requests

New Enterprise Project

{
  "input": "Build an enterprise healthcare management platform with patient records, appointment scheduling, billing, insurance processing, and HIPAA compliance for a multi-location hospital system.",
}

Complex Feature Addition

{
  "input": "Add AI-powered diagnostics, predictive analytics, and automated treatment recommendations to existing healthcare platform",
  "currentContext": "Existing platform has patient management, scheduling, basic reporting, built with React/Node.js/PostgreSQL, serves 50+ medical practices",
}

Async Processing

{
  "input": "Build a comprehensive fintech platform with banking, investments, crypto trading, regulatory compliance, and real-time market data",
  "async": true
}

Example: With Documentation URLs

{
  "input": "Build an enterprise healthcare platform with HIPAA compliance and telemedicine capabilities",
  "docURLs": [
    "https://docs.pre.dev",
    "https://docs.hl7.org"
  ],
  "async": true
}

Example: With File Upload

// Prepare file upload for enterprise requirements document
const formData = new FormData();
formData.append('file', enterpriseRequirementsFile); // PDF with detailed enterprise requirements
formData.append('input', 'Generate comprehensive deep spec for the uploaded enterprise platform requirements');
formData.append('docURLs', JSON.stringify([
  "https://docs.pre.dev",
  "https://docs.hl7.org",
  "https://enterprise-docs.company.com"
]));
formData.append('async', 'true');

const response = await fetch('https://api.pre.dev/deep-spec', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
    // Note: Don't set Content-Type for FormData - browser sets it automatically
  },
  body: formData
});

const result = await response.json();
console.log('Request ID:', result.requestId);

Example: File Upload with Existing Context

// Upload existing architecture docs and add context
const formData = new FormData();
formData.append('file', currentArchitectureFile); // Current system architecture
formData.append('input', 'Add microservices architecture and improve scalability for our existing healthcare platform');
formData.append('currentContext', 'Existing platform handles 100k+ patients, built with React/Node.js/PostgreSQL, has basic HIPAA compliance');
formData.append('async', 'true');

Response

Success Response (Sync Mode)

{
  "endpoint": "deep_spec",
  "input": "Build an enterprise healthcare management platform...",
  "status": "completed",
  "success": true,
  "humanSpecUrl": "https://api.pre.dev/s/a6hFJRV6",
  "codingAgentSpecUrl": "https://api.pre.dev/s/a6hFJRV7",
  "executionTime": 185000,
  "predevUrl": "https://pre.dev/projects/abc123",
  "lovableUrl": "https://lovable.dev/?autosubmit=true#prompt=First%20download%20https%3A%2F%2Fapi.pre.dev%2Fs%2Fa6hFJRV6%2C%20then%20save%20it%20to%20a%20file%20called%20%22spec.md%22%20and%20then%20parse%20it%20and%20implement%20it%20step%20by%20step",
  "cursorUrl": "cursor://anysphere.cursor-deeplink/prompt?text=First+download+https%3A%2F%2Fapi.pre.dev%2Fs%2Fa6hFJRV6%2C+then+save+it+to+a+file+called+%22spec.md%22+and+then+parse+it+and+implement+it+step+by+step",
  "v0Url": "https://v0.dev/chat?q=First%20download%20https%3A%2F%2Fapi.pre.dev%2Fs%2Fa6hFJRV6%2C%20then%20save%20it%20to%20a%20file%20called%20%22spec.md%22%20and%20then%20parse%20it%20and%20implement%20it%20step%20by%20step",
  "boltUrl": "https://bolt.new?prompt=First%20download%20https%3A%2F%2Fapi.pre.dev%2Fs%2Fa6hFJRV6%2C%20then%20save%20it%20to%20a%20file%20called%20%22spec.md%22%20and%20then%20parse%20it%20and%20implement%20it%20step%20by%20step",
  "zippedDocsUrls": [
    {
      "platform": "docs.hl7.org",
      "masterZipShortUrl": "https://api.pre.dev/s/xyz789"
    },
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "https://api.pre.dev/s/abc456"
    }
  ]
}

Field	Type	Description
`endpoint`	string	Endpoint used: `"deep_spec"`
`input`	string	Original input text provided
`status`	string	Completion status: `"completed"` when successful
`success`	boolean	Whether the request succeeded
`humanSpecUrl`	string	URL where the human-readable spec is hosted (downloadable markdown)
`totalHumanHours`	number	Estimated total hours for a human to implement the spec
`codingAgentSpecUrl`	string	URL where the coding agent spec format is hosted (downloadable markdown)
`executionTime`	number	Processing time in milliseconds
`predevUrl`	string	pre.dev project URL where you can view and edit the spec
`lovableUrl`	string	Deep link to Lovable.dev with auto-submit prompt to implement the spec
`cursorUrl`	string	Deep link to Cursor with prompt to download and implement the spec
`v0Url`	string	Deep link to Vercel v0 with prompt to implement the spec
`boltUrl`	string	Deep link to Bolt.new with prompt to implement the spec
`zippedDocsUrls`	array	New: Array of scraped documentation archives. Each object contains `platform` (hostname from the doc URL), `masterZipShortUrl` (download link to the ZIP archive), and optional `masterMarkdownShortUrl` (consolidated markdown). Empty array if no `docURLs` provided or scraping fails

Success Response (Async Mode)

Immediate response when async: true:

{
  "specId": "507f1f77bcf86cd799439011",
  "status": "pending"
}

Field	Type	Description
`specId`	string	Unique ID to poll for status (use with `/api/spec-status/:specId`)
`status`	string	Initial status: `"pending"`

Output Structure: Milestones → Stories → Subtasks

Deep Spec follows a three-level hierarchy for comprehensive implementation planning:

### - [ ] **Milestone 2**: User authentication and profile management

- [ ] **User Registration** - (M): As a: new user, I want to: register an account with email and password, So that: I can access the platform
  - **Acceptance Criteria:**
    - [ ] User can register with valid email and password
    - [ ] Email verification sent upon registration
    - [ ] Duplicate emails handled gracefully
    - [ ] Password strength requirements enforced
  - [ ] DB: Create/verify table_users migration - (M)
  - [ ] Infra: Configure Clerk (external_clerk) & auth settings - (M)
  - [ ] FE: Implement /RegisterPage UI comp_registerPage_mainForm - (M)
  - [ ] FE: Add client-side validation & reCAPTCHA on register form - (M)
  - [ ] API: Implement registerWithEmail mutation in router_route_registerPage - (M)
  - [ ] Backend: Create user record in table_users and auth_methods - (M)
  - [ ] Integration: Connect API to Clerk for email confirmation/session - (M)
  - [ ] QA: Write unit and integration tests for registration flow - (M)
  - [ ] Docs: Document registration API and front-end behavior - (M)

- [ ] **Password Reset** - (M): As a: registered user, I want to: reset my password securely, So that: I can regain access
  - **Acceptance Criteria:**
    - [ ] User can request password reset link via valid email
    - [ ] Reset link expires after a defined period
    - [ ] New password must meet strength requirements
    - [ ] System invalidates existing sessions after password change
  - [ ] DB: Create password_resets table migration - (M)
  - [ ] API: Implement requestPasswordReset mutation (validate, create token) - (M)
  - [ ] API: Implement verifyResetToken and finalizeReset mutation - (M)
  - [ ] Frontend: Add Password Reset Request page (/auth/password-reset) - (M)
  - [ ] Frontend: Add Password Reset Form page (/auth/reset?token=) - (M)
  - [ ] Auth Integration: Wire Clerk for account lookup and session invalidation - (M)
  - [ ] Infra: Email service integration and template for reset link - (M)
  - [ ] Security: Add reCAPTCHA and rate limiting to request endpoint - (M)
  - [ ] Testing: End-to-end tests for reset flow - (M)
  - [ ] Docs: Document API, pages, and operational runbook - (M)

Key Characteristics:

✅ High-level milestones group related features
✅ Detailed user stories with comprehensive acceptance criteria
✅ Granular implementation subtasks (DB, API, Frontend, Testing, Docs)
✅ Subtasks categorized by layer (DB, Infra, FE, API, Backend, QA, Docs)
✅ Task-level complexity estimates for precise planning

What Makes Deep Spec Different

Deep Spec provides enterprise-grade analysis that goes far beyond Fast Spec:

Enhanced Feature Analysis

Detailed user journey mapping for each feature
Comprehensive edge case analysis
Advanced user story elaboration with detailed acceptance criteria
Cross-feature dependency mapping

Advanced Architecture Planning

Detailed system design diagrams (when applicable)
Comprehensive database schema design
Advanced security architecture planning
Scalability modeling and capacity planning
Performance optimization strategies

Extensive Risk Assessment

Detailed technical risk analysis with mitigation strategies
Comprehensive security threat modeling
Regulatory compliance mapping (GDPR, HIPAA, SOX, etc.)
Operational risk assessment and business continuity planning

Enterprise-Ready Planning

Detailed implementation roadmap with critical path analysis
Resource allocation recommendations
Stakeholder communication strategies
Change management planning
Training and documentation requirements

When to Use Deep Spec

Enterprise Applications

Healthcare platforms with regulatory requirements
Financial systems with compliance needs
Large-scale SaaS platforms with complex workflows
Mission-critical internal tools

Complex System Requirements

Multi-tenant architectures
Real-time processing systems
High-throughput applications
Systems requiring 99.9%+ uptime

Large Team Coordination

Projects with 5+ developers
Cross-functional team collaboration
Extended development timelines (6+ months)
Projects requiring detailed handoffs

Code Examples

cURL - Enterprise Healthcare Platform

curl -X POST https://api.pre.dev/deep-spec \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "input": "Build an enterprise healthcare management platform with patient records, appointment scheduling, billing, insurance processing, telemedicine capabilities, and HIPAA compliance for a multi-location hospital system with 500+ providers.",
  }'

Python - Financial Services Platform

import requests

response = requests.post(
    'https://api.pre.dev/deep-spec',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    json={
        'input': 'Build a fintech platform with banking services, investment management, cryptocurrency trading, regulatory compliance (SEC, FINRA), and real-time market data integration for retail and institutional investors.',
        'async': True  # Deep specs benefit from async processing
    }
)

result = response.json()
print(f"Request ID: {result['requestId']}")

JavaScript - Complex SaaS Application

const response = await fetch('https://api.pre.dev/deep-spec', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    input: 'Build a comprehensive SaaS project management platform with advanced workflow automation, AI-powered insights, enterprise integrations, multi-tenant architecture, and real-time collaboration for teams of 1000+ users.',
    async: true
  })
});

const result = await response.json();
console.log(`Request ID: ${result.requestId}`);

Deep Spec Output Structure

1. Executive Summary & Business Case

Detailed problem statement and solution approach
Success metrics and KPIs
Stakeholder analysis
High-level timeline and milestones

2. Comprehensive Feature Catalog

Detailed feature specifications with user stories
Complex workflow documentation
Integration requirements mapping
Third-party service dependencies

3. Enterprise Architecture Design

System architecture diagrams
Database design specifications
API design and integration patterns
Security architecture blueprint

4. Implementation Strategy

Detailed development phases with dependencies
Critical path identification
Risk mitigation strategies
Quality assurance approach

5. Operational Considerations

Deployment strategy and environment planning
Monitoring and alerting requirements
Backup and disaster recovery planning
Support and maintenance guidelines

Documentation Scraping & Archives

Overview

When you provide docURLs in your request, Architect automatically scrapes the documentation in parallel with spec generation and packages it into downloadable ZIP archives. This is especially valuable for Deep Spec where you’re building complex enterprise systems with multiple integrations.

How It Works

Parallel Processing: Documentation scraping runs simultaneously with spec generation, so it doesn’t extend the already longer Deep Spec generation time
Graceful Degradation: If documentation scraping fails, spec generation still completes
Enterprise-Grade Archives: Each platform gets a well-organized ZIP with hierarchical structure

Response Field: `zippedDocsUrls`

interface ZippedDocsUrl {
  platform: string;              // Hostname from doc URL (e.g., "stripe.com", "docs.hl7.org")
  masterZipShortUrl: string;     // Download link to ZIP archive
  masterMarkdownShortUrl?: string; // Optional: consolidated markdown
}

Example: Healthcare Platform with Multiple Documentation Sources

{
  "input": "Build enterprise healthcare platform with HIPAA compliance, HL7 FHIR integration, and payment processing",
  "docURLs": [
    "https://docs.hl7.org/fhir",
    "https://docs.hl7.org/implementation",
    "https://stripe.com/docs/api",
    "https://www.hhs.gov/hipaa/for-professionals/security/guidance"
  ],
  "async": true
}

Response:

{
  "endpoint": "deep_spec",
  "codingAgentSpecUrl": "https://api.pre.dev/s/a6hFJRV6",
  "zippedDocsUrls": [
    {
      "platform": "docs.hl7.org",
      "masterZipShortUrl": "https://api.pre.dev/s/xyz789"
    },
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "https://api.pre.dev/s/abc456"
    },
    {
      "platform": "hhs.gov",
      "masterZipShortUrl": "https://api.pre.dev/s/def123"
    }
  ]
}

Enterprise Use Cases

Healthcare Systems:

HL7 FHIR implementation guides
HIPAA compliance documentation
Medical device integration specs
Telemedicine API documentation

Financial Services:

Payment gateway documentation (Stripe, Square)
Banking API specifications
Regulatory compliance guides (SEC, FINRA)
Cryptocurrency exchange APIs

Complex SaaS Platforms:

Third-party integration documentation
Enterprise SSO providers (Okta, Auth0)
Cloud infrastructure docs (AWS, GCP, Azure)
Analytics and monitoring platforms

ZIP Archive Structure

Enterprise documentation archives contain:

Individual markdown files per documentation page
Hierarchical folder structure mirroring the site
Organized by topic/section for easy navigation
Comprehensive coverage of scraped documentation

Best Practices for Enterprise Documentation

Do:

✅ Include compliance and regulatory documentation
✅ Add integration partner API docs
✅ Reference internal architecture documentation
✅ Include security and authentication specifications
✅ Provide infrastructure and deployment guides

Don’t:

❌ Duplicate URLs from the same domain
❌ Include marketing or sales pages
❌ Link to outdated or deprecated documentation
❌ Add overly broad documentation portals

Viewing Documentation Archives

Enterprise users access documentation archives through the API Usage Logs:

Visit https://pre.dev/enterprise/dashboard?page=api
Click any API call to open the log details modal
View “Documentation Archives” section
Download ZIP files for offline reference
Share archives with your development team

Integration with Deep Spec Workflow

Documentation archives complement Deep Spec’s detailed analysis:

During Generation: AI references provided docs for accurate integration specs
After Generation: Development team has complete documentation context
During Implementation: Developers download archives for detailed reference
For Review: Stakeholders can verify external dependencies and APIs

Error Handling

Scraping Failures:

zippedDocsUrls returns empty array []
Deep Spec generation completes normally
No errors thrown (graceful degradation)

Missing docURLs Parameter:

zippedDocsUrls returns empty array []
Deep Spec generation proceeds as normal

Partial Failures:

Successfully scraped platforms included in response
Failed platforms omitted from zippedDocsUrls
Deep Spec generation completes with available documentation

Best Practices for Deep Spec

Input Quality for Complex Projects

Detailed business requirements - Include specific compliance needs
Technical constraints - Existing systems, performance requirements
Scale expectations - User numbers, data volume, transaction rates
Integration landscape - Existing tools, APIs, third-party services
Documentation URLs - Provide comprehensive documentation for all external dependencies

Planning for Enterprise Projects

Allocate sufficient time - Deep specs can take 2-3 minutes
Use async mode for the best experience with complex inputs
Review thoroughly - Deep specs contain extensive detail requiring careful review
Share with stakeholders - Use as a comprehensive project brief
Distribute documentation archives - Ensure development team has complete context

Cost Considerations

Higher investment upfront - 50 credits vs 10 for Fast Spec
Significant time savings downstream - Reduces costly rework and scope changes
Better resource allocation - Clear requirements prevent over/under-engineering
Comprehensive documentation - Archives save hours of documentation gathering

Next: Check Status Endpoint

Monitor async specification processing progress.

Authorizations

Authorization

string

header

default:YOUR_API_KEY

required

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

Body

input

string

required

Description of what you want to build or the feature you want to add

Example:

"Build a SaaS project management tool with team collaboration and real-time updates"

currentContext

string

CRITICAL: Existing project/codebase context. When provided, generates feature addition spec. When omitted, generates full new project spec with setup, deployment, docs, maintenance

Example:

"Existing Next.js app with Supabase, has auth, task CRUD, team features"

docURLs

string<uri>[]

Optional array of documentation URLs that Architect will reference when generating specifications. Each URL is automatically scraped and packaged into downloadable ZIP archives organized by platform

Example:

[
  "https://docs.pre.dev",
  "https://docs.stripe.com"
]

async

boolean

default:false

If true, returns immediately with requestId for status polling. If false (default), waits for completion

Response

Specification generated successfully

Option 1
Option 2

endpoint

enum<string>

Which endpoint was used

Available options:

fast_spec,

deep_spec

input

string

Original input text provided

status

enum<string>

Completion status

Available options:

completed

success

boolean

Whether the request succeeded

humanSpecUrl

string<uri>

URL where the human-readable spec is hosted (downloadable markdown)

totalHumanHours

number

Estimated total hours for a human to implement the spec

codingAgentSpecUrl

string<uri>

URL where the coding agent spec format is hosted (downloadable markdown)

executionTime

integer

Processing time in milliseconds

predevUrl

string<uri>

pre.dev project URL where you can view and edit the spec

lovableUrl

string<uri>

Deep link to Lovable.dev with auto-submit prompt to implement the spec

cursorUrl

string

Deep link to Cursor with prompt to download and implement the spec

v0Url

string<uri>

Deep link to Vercel v0 with prompt to implement the spec

boltUrl

string<uri>

Deep link to Bolt.new with prompt to implement the spec

zippedDocsUrls

object[]

Array of scraped documentation archives. Empty array if no docURLs provided or scraping fails. Each object contains platform identifier and download links

Show child attributes

zippedDocsUrls.platform

string

required

Hostname extracted from the documentation URL (e.g., 'stripe.com', 'docs.github.com')

Example:

"stripe.com"

zippedDocsUrls.masterZipShortUrl

string<uri>

required

Short URL to download the zipped documentation archive for this platform

zippedDocsUrls.masterMarkdownShortUrl

string<uri>

Optional short URL to consolidated markdown file for this platform

Using the API

Spec Generation

Spec Management

​POST /deep-spec

​Overview

​Subscription Required

​Endpoint

​Headers

​Request Body

​Parameters

​Deep Spec vs Fast Spec

​Example Requests

​New Enterprise Project

​Complex Feature Addition

​Async Processing

​Example: With Documentation URLs

​Example: With File Upload

​Example: File Upload with Existing Context

​Response

​Success Response (Sync Mode)

​Success Response (Async Mode)

​Output Structure: Milestones → Stories → Subtasks

​What Makes Deep Spec Different

​Enhanced Feature Analysis

​Advanced Architecture Planning

​Extensive Risk Assessment

​Enterprise-Ready Planning

​When to Use Deep Spec

​Enterprise Applications

​Complex System Requirements

​Large Team Coordination

​Code Examples

​cURL - Enterprise Healthcare Platform

​Python - Financial Services Platform

​JavaScript - Complex SaaS Application

​Deep Spec Output Structure

​1. Executive Summary & Business Case

​2. Comprehensive Feature Catalog

​3. Enterprise Architecture Design

​4. Implementation Strategy

​5. Operational Considerations

​Documentation Scraping & Archives

​Overview

​How It Works

​Response Field: zippedDocsUrls

​Example: Healthcare Platform with Multiple Documentation Sources

​Enterprise Use Cases

​ZIP Archive Structure

​Best Practices for Enterprise Documentation

​Viewing Documentation Archives

​Integration with Deep Spec Workflow

​Error Handling

​Best Practices for Deep Spec

​Input Quality for Complex Projects

​Planning for Enterprise Projects

​Cost Considerations

Next: Check Status Endpoint

Authorizations

Body

Response

POST /deep-spec

Overview

Subscription Required

Endpoint

Headers

Request Body

Parameters

Deep Spec vs Fast Spec

Example Requests

New Enterprise Project

Complex Feature Addition

Async Processing

Example: With Documentation URLs

Example: With File Upload

Example: File Upload with Existing Context

Response

Success Response (Sync Mode)

Success Response (Async Mode)

Output Structure: Milestones → Stories → Subtasks

What Makes Deep Spec Different

Enhanced Feature Analysis

Advanced Architecture Planning

Extensive Risk Assessment

Enterprise-Ready Planning

When to Use Deep Spec

Enterprise Applications

Complex System Requirements

Large Team Coordination

Code Examples

cURL - Enterprise Healthcare Platform

Python - Financial Services Platform

JavaScript - Complex SaaS Application

Deep Spec Output Structure

1. Executive Summary & Business Case

2. Comprehensive Feature Catalog

3. Enterprise Architecture Design

4. Implementation Strategy

5. Operational Considerations

Documentation Scraping & Archives

Overview

How It Works

Response Field: `zippedDocsUrls`

Example: Healthcare Platform with Multiple Documentation Sources

Enterprise Use Cases

ZIP Archive Structure

Best Practices for Enterprise Documentation

Viewing Documentation Archives

Integration with Deep Spec Workflow

Error Handling

Best Practices for Deep Spec

Input Quality for Complex Projects

Planning for Enterprise Projects

Cost Considerations