Skip to main content
POST
/
deep-spec
curl --request POST \
--url https://api.pre.dev/deep-spec \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"input": "Build an enterprise healthcare management platform with patient records, appointment scheduling, billing, insurance processing, and HIPAA compliance for a multi-location hospital system",
"outputFormat": "url"
}'
{
  "endpoint": "fast_spec",
  "input": "<string>",
  "status": "completed",
  "success": true,
  "output": "<string>",
  "outputFormat": "url",
  "outputFileUrl": "<string>",
  "executionTime": 123,
  "predevUrl": "<string>",
  "lovableUrl": "<string>",
  "cursorUrl": "<string>",
  "v0Url": "<string>",
  "boltUrl": "<string>"
}

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:
ParameterTypeRequiredDescription
inputstringDescription of what you want to build
outputFormatstring"url" (default) - returns hosted URL, or "markdown" - returns raw markdown in response
currentContextstringCRITICAL: Existing project/codebase context. When provided, generates feature addition spec. When omitted, generates full new project spec with setup, deployment, docs, maintenance
docURLsstring[]Optional: Array of documentation URLs that Architect will reference when generating specifications. Useful for API documentation, design systems, or existing project docs
asyncbooleanfalse (default) - wait for completion, or true - return immediately with requestId for status polling
For file upload requests (multipart/form-data):
ParameterTypeRequiredDescription
fileFileOptional: File to be parsed as input (e.g., existing code, documentation, requirements). Can be used alone or combined with input text
inputstringOptional: Additional text description when using file upload. Can be empty string if using only file
outputFormatstring"url" (default) - returns hosted URL, or "markdown" - returns raw markdown in response
docURLsstring[]Optional: Array of documentation URLs that Architect will reference when generating specifications. Useful for API documentation, design systems, or existing project docs
asyncbooleanfalse (default) - wait for completion, or true - return immediately with requestId for status polling

Deep Spec vs Fast Spec

FeatureFast SpecDeep Spec
Cost10 credits50 credits
Processing Time30-40 sec2-3 min
StructureMilestones → StoriesMilestones → Stories → Subtasks
Detail LevelComprehensiveUltra-detailed
Best ForMVPs, prototypesEnterprise, 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.",
  "outputFormat": "url"
}

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",
  "outputFormat": "url"
}

Async Processing

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

Example: With Documentation URLs

{
  "input": "Build an enterprise healthcare platform with HIPAA compliance and telemedicine capabilities",
  "outputFormat": "url",
  "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('outputFormat', 'url');
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('outputFormat', 'markdown');
formData.append('async', 'true');

Response

Success Response (Sync Mode)

{
  "endpoint": "deep_spec",
  "input": "Build an enterprise healthcare management platform...",
  "status": "completed",
  "success": true,
  "output": "https://api.pre.dev/s/a6hFJRV6",
  "outputFormat": "url",
  "outputFileUrl": "https://api.pre.dev/s/a6hFJRV6",
  "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"
}
FieldTypeDescription
endpointstringEndpoint used: "deep_spec"
inputstringOriginal input text provided
statusstringCompletion status: "completed" when successful
successbooleanWhether the request succeeded
outputanyPrimary output - the hosted spec URL or markdown content
outputFormatstringFormat used: "url" or "markdown"
outputFileUrlstringURL where the spec file is hosted (downloadable markdown)
executionTimenumberProcessing time in milliseconds
predevUrlstringpre.dev project URL where you can view and edit the spec
lovableUrlstringDeep link to Lovable.dev with auto-submit prompt to implement the spec
cursorUrlstringDeep link to Cursor with prompt to download and implement the spec
v0UrlstringDeep link to Vercel v0 with prompt to implement the spec
boltUrlstringDeep link to Bolt.new with prompt to implement the spec
When outputFormat: "markdown":
{
  "endpoint": "deep_spec",
  "input": "Build an enterprise healthcare management platform...",
  "status": "completed",
  "success": true,
  "output": "# Enterprise Healthcare Platform Specification\n\n## Executive Summary...",
  "outputFormat": "markdown",
  "outputFileUrl": "https://api.pre.dev/s/a6hFJRV6",
  "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"
}

Success Response (Async Mode)

Immediate response when async: true:
{
  "specId": "507f1f77bcf86cd799439011",
  "status": "pending"
}
FieldTypeDescription
specIdstringUnique ID to poll for status (use with /api/spec-status/:specId)
statusstringInitial 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.",
    "outputFormat": "url"
  }'

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.',
        'outputFormat': 'url',
        '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.',
    outputFormat: 'url',
    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

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

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

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

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"

outputFormat
enum<string>
default:url

Output format: 'url' returns a hosted URL (default), 'markdown' returns raw markdown content

Available options:
url,
markdown
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

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

output

Primary output - the hosted spec URL or markdown content

outputFormat
enum<string>

Format used

Available options:
url,
markdown
outputFileUrl
string<uri>

URL where the spec file 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

I