Generate Deep Spec

curl --request POST \
  --url https://api.pre.dev/deep-spec \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "Build a SaaS project management tool with team collaboration and real-time updates",
  "currentContext": "Existing Next.js app with Supabase, has auth, task CRUD, team features",
  "docURLs": [
    "https://docs.pre.dev",
    "https://docs.stripe.com"
  ],
  "async": false
}
'

import requests

url = "https://api.pre.dev/deep-spec"

payload = {
    "input": "Build a SaaS project management tool with team collaboration and real-time updates",
    "currentContext": "Existing Next.js app with Supabase, has auth, task CRUD, team features",
    "docURLs": ["https://docs.pre.dev", "https://docs.stripe.com"],
    "async": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: 'Build a SaaS project management tool with team collaboration and real-time updates',
    currentContext: 'Existing Next.js app with Supabase, has auth, task CRUD, team features',
    docURLs: ['https://docs.pre.dev', 'https://docs.stripe.com'],
    async: false
  })
};

fetch('https://api.pre.dev/deep-spec', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pre.dev/deep-spec",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'Build a SaaS project management tool with team collaboration and real-time updates',
    'currentContext' => 'Existing Next.js app with Supabase, has auth, task CRUD, team features',
    'docURLs' => [
        'https://docs.pre.dev',
        'https://docs.stripe.com'
    ],
    'async' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pre.dev/deep-spec"

	payload := strings.NewReader("{\n  \"input\": \"Build a SaaS project management tool with team collaboration and real-time updates\",\n  \"currentContext\": \"Existing Next.js app with Supabase, has auth, task CRUD, team features\",\n  \"docURLs\": [\n    \"https://docs.pre.dev\",\n    \"https://docs.stripe.com\"\n  ],\n  \"async\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pre.dev/deep-spec")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"Build a SaaS project management tool with team collaboration and real-time updates\",\n  \"currentContext\": \"Existing Next.js app with Supabase, has auth, task CRUD, team features\",\n  \"docURLs\": [\n    \"https://docs.pre.dev\",\n    \"https://docs.stripe.com\"\n  ],\n  \"async\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pre.dev/deep-spec")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"Build a SaaS project management tool with team collaboration and real-time updates\",\n  \"currentContext\": \"Existing Next.js app with Supabase, has auth, task CRUD, team features\",\n  \"docURLs\": [\n    \"https://docs.pre.dev\",\n    \"https://docs.stripe.com\"\n  ],\n  \"async\": false\n}"

response = http.request(request)
puts response.read_body

{
  "input": "<string>",
  "status": "completed",
  "success": true,
  "humanSpecUrl": "<string>",
  "totalHumanHours": 123,
  "architectureInfographicUrl": "<string>",
  "codingAgentSpecUrl": "<string>",
  "codingAgentSpecJson": {
    "executiveSummary": "<string>",
    "coreFunctionalities": [
      {
        "name": "<string>",
        "description": "<string>"
      }
    ],
    "techStack": [
      {
        "name": "<string>",
        "category": "<string>"
      }
    ],
    "milestones": [
      {
        "milestoneNumber": 123,
        "description": "<string>",
        "stories": [
          {
            "title": "<string>",
            "subTasks": [
              {
                "description": "<string>",
                "id": "<string>"
              }
            ],
            "id": "<string>",
            "description": "<string>",
            "acceptanceCriteria": [
              "<string>"
            ],
            "complexity": "<string>"
          }
        ]
      }
    ],
    "title": "<string>",
    "techStackGrouped": {}
  },
  "codingAgentSpecMarkdown": "<string>",
  "humanSpecJson": {
    "executiveSummary": "<string>",
    "coreFunctionalities": [
      {
        "name": "<string>",
        "description": "<string>"
      }
    ],
    "personas": [
      {
        "title": "<string>",
        "description": "<string>",
        "primaryGoals": [
          "<string>"
        ],
        "painPoints": [
          "<string>"
        ],
        "keyTasks": [
          "<string>"
        ]
      }
    ],
    "techStack": [
      {
        "name": "<string>",
        "category": "<string>"
      }
    ],
    "milestones": [
      {
        "milestoneNumber": 123,
        "description": "<string>",
        "hours": 123,
        "stories": [
          {
            "title": "<string>",
            "hours": 123,
            "subTasks": [
              {
                "description": "<string>",
                "hours": 123,
                "complexity": "<string>",
                "id": "<string>",
                "roles": [
                  {
                    "name": "<string>",
                    "shortHand": "<string>"
                  }
                ]
              }
            ],
            "id": "<string>",
            "description": "<string>",
            "acceptanceCriteria": [
              "<string>"
            ],
            "complexity": "<string>"
          }
        ]
      }
    ],
    "totalHours": 123,
    "roles": [
      {
        "name": "<string>",
        "shortHand": "<string>"
      }
    ],
    "title": "<string>",
    "techStackGrouped": {}
  },
  "humanSpecMarkdown": "<string>",
  "executionTime": 123,
  "predevUrl": "<string>",
  "zippedDocsUrls": [
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "<string>",
      "masterMarkdownShortUrl": "<string>"
    }
  ],
  "creditsUsed": 123,
  "userFlowGraph": {
    "nodes": [
      {
        "id": "<string>",
        "label": "<string>",
        "type": "<string>",
        "description": "<string>",
        "level": 123,
        "hours": 123
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "description": "<string>",
        "edgeType": "<string>"
      }
    ]
  },
  "architectureGraph": {
    "nodes": [
      {
        "id": "<string>",
        "label": "<string>",
        "type": "<string>",
        "description": "<string>",
        "level": 123,
        "hours": 123
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "description": "<string>",
        "edgeType": "<string>"
      }
    ]
  },
  "enrichedTechStack": [
    {
      "name": "<string>",
      "useFor": "<string>",
      "reason": "<string>",
      "description": "<string>",
      "link": "<string>",
      "helpfulLinks": [
        {
          "url": "<string>",
          "description": "<string>"
        }
      ],
      "alternatives": [
        {
          "name": "<string>",
          "link": "<string>",
          "description": "<string>"
        }
      ]
    }
  ]
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing Authorization header"
}

{
  "error": "Insufficient credits",
  "message": "You have insufficient credits to generate a spec. Please purchase more credits or upgrade your plan.",
  "generationsAvailable": 0
}

{
  "error": "Subscription required",
  "message": "Deep Spec requires Solo Premium or Enterprise subscription"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

POST

deep-spec

Generate Deep Spec

curl --request POST \
  --url https://api.pre.dev/deep-spec \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "Build a SaaS project management tool with team collaboration and real-time updates",
  "currentContext": "Existing Next.js app with Supabase, has auth, task CRUD, team features",
  "docURLs": [
    "https://docs.pre.dev",
    "https://docs.stripe.com"
  ],
  "async": false
}
'

import requests

url = "https://api.pre.dev/deep-spec"

payload = {
    "input": "Build a SaaS project management tool with team collaboration and real-time updates",
    "currentContext": "Existing Next.js app with Supabase, has auth, task CRUD, team features",
    "docURLs": ["https://docs.pre.dev", "https://docs.stripe.com"],
    "async": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: 'Build a SaaS project management tool with team collaboration and real-time updates',
    currentContext: 'Existing Next.js app with Supabase, has auth, task CRUD, team features',
    docURLs: ['https://docs.pre.dev', 'https://docs.stripe.com'],
    async: false
  })
};

fetch('https://api.pre.dev/deep-spec', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pre.dev/deep-spec",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'Build a SaaS project management tool with team collaboration and real-time updates',
    'currentContext' => 'Existing Next.js app with Supabase, has auth, task CRUD, team features',
    'docURLs' => [
        'https://docs.pre.dev',
        'https://docs.stripe.com'
    ],
    'async' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pre.dev/deep-spec"

	payload := strings.NewReader("{\n  \"input\": \"Build a SaaS project management tool with team collaboration and real-time updates\",\n  \"currentContext\": \"Existing Next.js app with Supabase, has auth, task CRUD, team features\",\n  \"docURLs\": [\n    \"https://docs.pre.dev\",\n    \"https://docs.stripe.com\"\n  ],\n  \"async\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pre.dev/deep-spec")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"Build a SaaS project management tool with team collaboration and real-time updates\",\n  \"currentContext\": \"Existing Next.js app with Supabase, has auth, task CRUD, team features\",\n  \"docURLs\": [\n    \"https://docs.pre.dev\",\n    \"https://docs.stripe.com\"\n  ],\n  \"async\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pre.dev/deep-spec")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"Build a SaaS project management tool with team collaboration and real-time updates\",\n  \"currentContext\": \"Existing Next.js app with Supabase, has auth, task CRUD, team features\",\n  \"docURLs\": [\n    \"https://docs.pre.dev\",\n    \"https://docs.stripe.com\"\n  ],\n  \"async\": false\n}"

response = http.request(request)
puts response.read_body

{
  "input": "<string>",
  "status": "completed",
  "success": true,
  "humanSpecUrl": "<string>",
  "totalHumanHours": 123,
  "architectureInfographicUrl": "<string>",
  "codingAgentSpecUrl": "<string>",
  "codingAgentSpecJson": {
    "executiveSummary": "<string>",
    "coreFunctionalities": [
      {
        "name": "<string>",
        "description": "<string>"
      }
    ],
    "techStack": [
      {
        "name": "<string>",
        "category": "<string>"
      }
    ],
    "milestones": [
      {
        "milestoneNumber": 123,
        "description": "<string>",
        "stories": [
          {
            "title": "<string>",
            "subTasks": [
              {
                "description": "<string>",
                "id": "<string>"
              }
            ],
            "id": "<string>",
            "description": "<string>",
            "acceptanceCriteria": [
              "<string>"
            ],
            "complexity": "<string>"
          }
        ]
      }
    ],
    "title": "<string>",
    "techStackGrouped": {}
  },
  "codingAgentSpecMarkdown": "<string>",
  "humanSpecJson": {
    "executiveSummary": "<string>",
    "coreFunctionalities": [
      {
        "name": "<string>",
        "description": "<string>"
      }
    ],
    "personas": [
      {
        "title": "<string>",
        "description": "<string>",
        "primaryGoals": [
          "<string>"
        ],
        "painPoints": [
          "<string>"
        ],
        "keyTasks": [
          "<string>"
        ]
      }
    ],
    "techStack": [
      {
        "name": "<string>",
        "category": "<string>"
      }
    ],
    "milestones": [
      {
        "milestoneNumber": 123,
        "description": "<string>",
        "hours": 123,
        "stories": [
          {
            "title": "<string>",
            "hours": 123,
            "subTasks": [
              {
                "description": "<string>",
                "hours": 123,
                "complexity": "<string>",
                "id": "<string>",
                "roles": [
                  {
                    "name": "<string>",
                    "shortHand": "<string>"
                  }
                ]
              }
            ],
            "id": "<string>",
            "description": "<string>",
            "acceptanceCriteria": [
              "<string>"
            ],
            "complexity": "<string>"
          }
        ]
      }
    ],
    "totalHours": 123,
    "roles": [
      {
        "name": "<string>",
        "shortHand": "<string>"
      }
    ],
    "title": "<string>",
    "techStackGrouped": {}
  },
  "humanSpecMarkdown": "<string>",
  "executionTime": 123,
  "predevUrl": "<string>",
  "zippedDocsUrls": [
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "<string>",
      "masterMarkdownShortUrl": "<string>"
    }
  ],
  "creditsUsed": 123,
  "userFlowGraph": {
    "nodes": [
      {
        "id": "<string>",
        "label": "<string>",
        "type": "<string>",
        "description": "<string>",
        "level": 123,
        "hours": 123
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "description": "<string>",
        "edgeType": "<string>"
      }
    ]
  },
  "architectureGraph": {
    "nodes": [
      {
        "id": "<string>",
        "label": "<string>",
        "type": "<string>",
        "description": "<string>",
        "level": 123,
        "hours": 123
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "description": "<string>",
        "edgeType": "<string>"
      }
    ]
  },
  "enrichedTechStack": [
    {
      "name": "<string>",
      "useFor": "<string>",
      "reason": "<string>",
      "description": "<string>",
      "link": "<string>",
      "helpfulLinks": [
        {
          "url": "<string>",
          "description": "<string>"
        }
      ],
      "alternatives": [
        {
          "name": "<string>",
          "link": "<string>",
          "description": "<string>"
        }
      ]
    }
  ]
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing Authorization header"
}

{
  "error": "Insufficient credits",
  "message": "You have insufficient credits to generate a spec. Please purchase more credits or upgrade your plan.",
  "generationsAvailable": 0
}

{
  "error": "Subscription required",
  "message": "Deep Spec requires Solo Premium or Enterprise subscription"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

Generate an ultra-detailed, comprehensive project specification.

Overview

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

Availability

Deep Spec consumes more credits than Fast Spec and is available on paid plans. See pre.dev/pricing for which plans include it.

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 `specId` 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 `specId` for status polling

Deep Spec vs Fast Spec

Feature	Fast Spec	Deep Spec
Cost	~5-10 credits	~10-50 credits
Processing Time	~1 min	~3-5 min
Structure	Milestones → Stories	Milestones → Stories → Subtasks
Detail Level	Comprehensive	Ultra-detailed
Best For	MVPs, prototypes	Enterprise, complex systems

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('Spec ID:', result.specId);

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",
  "codingAgentSpecJson": {
    "executiveSummary": "An enterprise healthcare platform...",
    "coreFunctionalities": [
      { "name": "Patient Records", "description": "Secure patient data management", "priority": "High" }
    ],
    "techStack": [
      { "name": "React", "category": "Frontend" },
      { "name": "Node.js", "category": "Backend" }
    ],
    "techStackGrouped": { "Frontend": ["React"], "Backend": ["Node.js"] },
    "milestones": [
      {
        "milestoneNumber": 1,
        "description": "Patient Management",
        "stories": [
          {
            "title": "Patient intake",
            "complexity": "M",
            "subTasks": [{ "description": "Design intake workflow", "complexity": "S" }]
          }
        ]
      }
    ]
  },
  "codingAgentSpecMarkdown": "# Enterprise Healthcare Platform\\n\\n## Executive Summary\\n...",
  "humanSpecJson": {
    "executiveSummary": "An enterprise healthcare platform...",
    "personas": [{ "title": "Clinician", "description": "Provides care and updates records" }],
    "roles": [{ "name": "Backend Engineer", "shortHand": "BE" }],
    "techStack": [{ "name": "PostgreSQL", "category": "Database" }],
    "techStackGrouped": { "Database": ["PostgreSQL"] },
    "totalHours": 320,
    "milestones": [
      {
        "milestoneNumber": 1,
        "description": "Patient Management",
        "hours": 110,
        "stories": [
          {
            "title": "Patient intake",
            "hours": 16,
            "subTasks": [{ "description": "Implement intake API", "hours": 6, "complexity": "M" }]
          }
        ]
      }
    ]
  },
  "humanSpecMarkdown": "# Enterprise Healthcare Platform\\n\\n## Executive Summary\\n...",
  "architectureInfographicUrl": "https://res.cloudinary.com/dfvg7gm6w/image/upload/v1765403270/infographics/arch_infographic_cfac141b_1765403269989_0.jpg",
  "executionTime": 185000,
  "predevUrl": "https://pre.dev/projects/abc123",
  "creditsUsed": 28,
  "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)
`humanSpecMarkdown`	string	Full markdown SOW with all details
`humanSpecJson`	object	Full structured SOW JSON (hours, personas, roles)
`totalHumanHours`	number	Estimated total hours for a human to implement the spec
`architectureInfographicUrl`	string	URL to a visual architecture infographic/diagram for the specification
`codingAgentSpecUrl`	string	URL where the coding agent spec format is hosted (downloadable markdown)
`codingAgentSpecMarkdown`	string	Simplified markdown SOW for AI tools
`codingAgentSpecJson`	object	Simplified structured SOW JSON for AI tools
`executionTime`	number	Processing time in milliseconds
`predevUrl`	string	pre.dev project URL where you can view and edit the spec
`creditsUsed`	number	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
`zippedDocsUrls`	array	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 `/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

Direct SOW Formats

Deep Spec returns the full Scope of Work inline, and also provides URL endpoints:

codingAgentSpecJson / codingAgentSpecMarkdown: concise outputs for AI coding assistants (no hours/personas/roles)
humanSpecJson / humanSpecMarkdown: full outputs with hours, personas, and roles for stakeholder review

Use cases:

Feed Cursor/Copilot: codingAgentSpecJson or codingAgentSpecMarkdown
Display in PM tools or dashboards: humanSpecJson
Export/PDF for clients: humanSpecMarkdown
Quick effort check: totalHumanHours or humanSpecJson.totalHours

Type definitions (shared by Fast and Deep Spec)

Coding Agent JSON (concise, no hours/personas/roles):

interface CodingAgentSpecJson {
  title?: string;
  executiveSummary: string;
  coreFunctionalities: SpecCoreFunctionality[];
  techStack: SpecTechStackItem[];
  techStackGrouped: Record<string, string[]>;
  milestones: CodingAgentMilestone[];
}

interface CodingAgentMilestone {
  milestoneNumber: number;
  description: string;
  stories: CodingAgentStory[];
}

interface CodingAgentStory {
  id?: string;
  title: string;
  description?: string;
  acceptanceCriteria?: string[];
  complexity?: string;
  subTasks: CodingAgentSubTask[];
}

interface CodingAgentSubTask {
  id?: string;
  description: string;
  complexity: string; // "S" | "M" | "L" | "XL"
}

Human JSON (full detail with hours/personas/roles):

interface HumanSpecJson {
  title?: string;
  executiveSummary: string;
  coreFunctionalities: SpecCoreFunctionality[];
  personas: SpecPersona[];
  techStack: SpecTechStackItem[];
  techStackGrouped: Record<string, string[]>;
  milestones: HumanSpecMilestone[];
  totalHours: number;
  roles: SpecRole[];
}

interface HumanSpecMilestone {
  milestoneNumber: number;
  description: string;
  hours: number;
  stories: HumanSpecStory[];
}

interface HumanSpecStory {
  id?: string;
  title: string;
  description?: string;
  acceptanceCriteria?: string[];
  hours: number;
  complexity?: string;
  subTasks: HumanSpecSubTask[];
}

interface HumanSpecSubTask {
  id?: string;
  description: string;
  hours: number;
  complexity: string;
  roles?: SpecRole[];
}

interface SpecPersona {
  title: string;
  description: string;
  primaryGoals?: string[];
  painPoints?: string[];
  keyTasks?: string[];
}

interface SpecRole {
  name: string;
  shortHand: string;
}

interface SpecCoreFunctionality {
  name: string;
  description: string;
  priority?: string; // "High" | "Medium" | "Low"
}

interface SpecTechStackItem {
  name: string;
  category: string;
}

What Makes Deep Spec Different

Deep Spec goes beyond Fast Spec in four ways: richer feature analysis (user journeys, edge cases, cross-feature dependencies), deeper architecture planning (schemas, security, scalability), broader risk assessment (technical, security, compliance), and a fuller implementation roadmap (critical path, resourcing, handoffs). If you’re choosing between the two, see Fast vs Deep Specs — the short version: reach for Deep Spec on complex, multi-team, or compliance-heavy systems.

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"Spec ID: {result['specId']}")

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(`Spec ID: ${result.specId}`);

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 feature helps AI agents and developers have context about external APIs, design systems, or frameworks referenced in the spec.

How It Works

Parallel Processing: Documentation scraping runs simultaneously with spec generation (not sequentially), so it doesn’t slow down your request
Graceful Degradation: If documentation scraping fails, spec generation still completes successfully
Organized Archives: Each platform gets its own ZIP with hierarchical folder structure based on the documentation site

Response Field: `zippedDocsUrls`

interface ZippedDocsUrl {
  platform: string;              // Hostname extracted from doc URL (e.g., "stripe.com", "docs.github.com")
  masterZipShortUrl: string;     // Short URL to download the ZIP archive
  masterMarkdownShortUrl?: string; // Optional: consolidated markdown file
}

Example Request with Documentation URLs

{
  "input": "Build a payment processing system with Stripe integration",
  "docURLs": [
    "https://stripe.com/docs/api",
    "https://stripe.com/docs/payments",
    "https://docs.github.com/en/rest"
  ]
}

Example Response with Documentation Archives

{
  "endpoint": "fast_spec",
  "codingAgentSpecUrl": "https://api.pre.dev/s/a6hFJRV6",
  "zippedDocsUrls": [
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "https://api.pre.dev/s/xyz789"
    },
    {
      "platform": "docs.github.com",
      "masterZipShortUrl": "https://api.pre.dev/s/abc456"
    }
  ]
}

ZIP Archive Structure

Each ZIP archive contains:

Individual markdown files (one per scraped page)
Hierarchical folder structure mirroring the documentation site
Organized by documentation site structure

Supported Domain Formats

The system handles various domain formats:

.com, .io, .org, .net
.cloud, .dev, .ai
Country-specific TLDs (.co.uk, .com.au, etc.)
Newer TLDs (.tech, .app, etc.)

Best Practices for Documentation URLs

Do:

✅ Provide specific documentation pages relevant to your spec
✅ Include API documentation for integrations you’re building
✅ Reference design system docs for UI consistency
✅ Use official documentation sources

Don’t:

❌ Include general marketing pages
❌ Link to blog posts instead of official documentation
❌ Reference deprecated or outdated documentation
❌ Link to non-documentation content

Viewing Documentation Archives

Enterprise users can view and download documentation archives from the API Usage Logs browser:

Navigate to https://pre.dev/enterprise/dashboard?page=api
Click on any API call to open the details modal
View the “Documentation Archives” section
Click download links to get the ZIP files

Error Handling

If documentation scraping fails:

zippedDocsUrls will be an empty array []
Spec generation continues normally
No error is thrown (graceful degradation)

If docURLs is not provided or is an empty array:

zippedDocsUrls will be an empty array []
Spec generation proceeds normally

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 ~3-5 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

Credits are charged per-inference based on actual token usage: ~10-50 credits for Deep Spec vs ~5-10 for Fast Spec. See Plans & Credits.

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/key (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

architectureInfographicUrl

string<uri>

URL to a visual architecture infographic/diagram for the specification

codingAgentSpecUrl

string<uri>

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

codingAgentSpecJson

object

Structured JSON spec optimized for AI coding assistants (excludes hours, personas, roles)

Show child attributes

codingAgentSpecMarkdown

string

Markdown spec optimized for AI coding assistants

humanSpecJson

object

Full structured JSON spec with hours, personas, and roles for human review

Show child attributes

humanSpecMarkdown

string

Full markdown spec with all details for human review

executionTime

integer

Processing time in milliseconds

predevUrl

string<uri>

pre.dev project URL where you can view and edit 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

creditsUsed

number

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

object

User flow graph with nodes representing user stories/flows and edges showing navigation paths (only when completed)

Show child attributes

architectureGraph

object

System architecture graph with C1/C2 level nodes and their relationships (only when completed)

Show child attributes

enrichedTechStack

object[]

Enriched tech stack with detailed reasons, descriptions, and alternatives for each technology (only when completed)

Show child attributes

Generate Fast Spec Spec Status

⌘I

​Overview

​Availability

​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

​Direct SOW Formats

​Type definitions (shared by Fast and Deep Spec)

​What Makes Deep Spec Different

​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 Request with Documentation URLs

​Example Response with Documentation Archives

​ZIP Archive Structure

​Supported Domain Formats

​Best Practices for Documentation URLs

​Viewing Documentation Archives

​Error Handling

​Best Practices for Deep Spec

​Input Quality for Complex Projects

​Planning for Enterprise Projects

​Cost

Next: Check Status Endpoint

Authorizations

Body

Response

Overview

Availability

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

Direct SOW Formats

Type definitions (shared by Fast and Deep Spec)

What Makes Deep Spec Different

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 Request with Documentation URLs

Example Response with Documentation Archives

ZIP Archive Structure

Supported Domain Formats

Best Practices for Documentation URLs

Viewing Documentation Archives

Error Handling

Best Practices for Deep Spec

Input Quality for Complex Projects

Planning for Enterprise Projects

Cost