> ## 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. # Generate Deep Spec > Complete documentation for the Deep Spec endpoint. Generate exhaustive, enterprise-grade project specifications. # POST /deep-spec 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:** \~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 | \~5-10 credits | \~10-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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "input": "Build a comprehensive fintech platform with banking, investments, crypto trading, regulatory compliance, and real-time market data", "async": true } ``` ### Example: With Documentation URLs ```json theme={null} { "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 ```javascript theme={null} // 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 ```javascript theme={null} // 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) ```json theme={null} { "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 | **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`:** ```json theme={null} { "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: ```markdown theme={null} ### - [ ] **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 across Fast/Deep) ```typescript theme={null} interface CodingAgentSpecJson { title?: string; executiveSummary: string; coreFunctionalities: SpecCoreFunctionality[]; techStack: SpecTechStackItem[]; techStackGrouped: Record; 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" } interface HumanSpecJson { title?: string; executiveSummary: string; coreFunctionalities: SpecCoreFunctionality[]; personas: SpecPersona[]; techStack: SpecTechStackItem[]; techStackGrouped: Record; 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 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 ```bash theme={null} 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 ```python theme={null} 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 ```javascript theme={null} 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 1. **Parallel Processing:** Documentation scraping runs simultaneously with spec generation, so it doesn't extend the already longer Deep Spec generation time 2. **Graceful Degradation:** If documentation scraping fails, spec generation still completes 3. **Enterprise-Grade Archives:** Each platform gets a well-organized ZIP with hierarchical structure ### Response Field: `zippedDocsUrls` ```typescript theme={null} 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 ```json theme={null} { "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:** ```json theme={null} { "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: 1. Visit [https://pre.dev/enterprise/dashboard?page=api](https://pre.dev/enterprise/dashboard?page=api) 2. Click any API call to open the log details modal 3. View "Documentation Archives" section 4. Download ZIP files for offline reference 5. Share archives with your development team ### Integration with Deep Spec Workflow Documentation archives complement Deep Spec's detailed analysis: 1. **During Generation:** AI references provided docs for accurate integration specs 2. **After Generation:** Development team has complete documentation context 3. **During Implementation:** Developers download archives for detailed reference 4. **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 * **Variable pricing** - Credits charged per-inference based on actual token usage (\~10-50 credits for Deep Spec vs \~5-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 Monitor async specification processing progress. ## OpenAPI ````yaml POST /deep-spec openapi: 3.1.0 info: title: pre.dev Architect API description: >- Generate comprehensive software specifications for coding agents. The Architect API helps you create detailed project specifications that AI coding agents can understand and implement. version: 1.1.0 contact: name: pre.dev Support url: https://pre.dev email: support@pre.dev license: name: Proprietary url: https://pre.dev/terms servers: - url: https://api.pre.dev description: Production API Server security: - apiKeyAuth: [] tags: - name: Spec Generation description: Generate comprehensive software specifications for AI coding agents - name: Status description: Check status of asynchronous specification processing - name: Spec Management description: List and search existing specifications - name: Account description: Manage user account and credits - name: Batches description: Submit and retrieve browser-agent task batches paths: /deep-spec: post: tags: - Spec Generation summary: Generate Deep Spec description: >- Generate an ultra-detailed, enterprise-grade project specification. Best for complex systems, enterprise applications, and critical projects. Cost: Variable (~10-50 credits based on complexity). Processing time: ~2-3 minutes. Requires Solo Premium or Enterprise subscription. operationId: generateDeepSpec requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SpecRequest' examples: enterpriseProject: summary: Enterprise Healthcare Platform value: input: >- Build an enterprise healthcare management platform with patient records, appointment scheduling, billing, insurance processing, and HIPAA compliance for a multi-location hospital system complexFeature: summary: Complex Feature Addition value: input: >- Add AI-powered diagnostics, predictive analytics, and automated treatment recommendations currentContext: >- Existing platform has patient management, scheduling, basic reporting, built with React/Node.js/PostgreSQL, serves 50+ medical practices asyncProcessing: summary: Async Processing value: input: >- Build a comprehensive fintech platform with banking, investments, crypto trading, regulatory compliance, and real-time market data async: true multipart/form-data: schema: $ref: '#/components/schemas/FileUploadRequest' responses: '200': description: Specification generated successfully content: application/json: schema: oneOf: - $ref: '#/components/schemas/SpecResponse' - $ref: '#/components/schemas/AsyncResponse' '400': description: Bad Request - Invalid input parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized message: Invalid or missing Authorization header '402': description: Payment Required - Insufficient credits content: application/json: schema: $ref: '#/components/schemas/InsufficientCreditsError' '403': description: Forbidden - Subscription required content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Subscription required message: Deep Spec requires Solo Premium or Enterprise subscription '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKeyAuth: [] components: schemas: SpecRequest: type: object required: - input properties: input: type: string description: 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: type: string description: >- 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: type: array items: type: string format: uri description: >- 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: type: boolean default: false description: >- If true, returns immediately with requestId for status polling. If false (default), waits for completion FileUploadRequest: type: object properties: file: type: string format: binary description: >- Optional file to be parsed as input (e.g., existing code, documentation, requirements). Can be used alone or combined with input text input: type: string description: >- Optional additional text description when using file upload. Can be empty string if using only file docURLs: type: array items: type: string description: JSON stringified array of documentation URLs async: type: boolean default: false SpecResponse: type: object properties: endpoint: type: string enum: - fast_spec - deep_spec description: Which endpoint was used input: type: string description: Original input text provided status: type: string enum: - completed description: Completion status success: type: boolean description: Whether the request succeeded humanSpecUrl: type: string format: uri description: URL where the human-readable spec is hosted (downloadable markdown) totalHumanHours: type: number description: Estimated total hours for a human to implement the spec architectureInfographicUrl: type: string format: uri description: >- URL to a visual architecture infographic/diagram for the specification codingAgentSpecUrl: type: string format: uri description: >- URL where the coding agent spec format is hosted (downloadable markdown) codingAgentSpecJson: $ref: '#/components/schemas/CodingAgentSpecJson' description: >- Structured JSON spec optimized for AI coding assistants (excludes hours, personas, roles) codingAgentSpecMarkdown: type: string description: Markdown spec optimized for AI coding assistants humanSpecJson: $ref: '#/components/schemas/HumanSpecJson' description: >- Full structured JSON spec with hours, personas, and roles for human review humanSpecMarkdown: type: string description: Full markdown spec with all details for human review executionTime: type: integer description: Processing time in milliseconds predevUrl: type: string format: uri description: pre.dev project URL where you can view and edit the spec zippedDocsUrls: type: array description: >- Array of scraped documentation archives. Empty array if no docURLs provided or scraping fails. Each object contains platform identifier and download links items: $ref: '#/components/schemas/ZippedDocsUrl' creditsUsed: type: number description: >- Total credits consumed by this spec generation. Available in real-time during processing and persisted on completion. Typical values: Fast spec ~5-10, Deep spec ~10-50. userFlowGraph: $ref: '#/components/schemas/SpecGraph' description: >- User flow graph with nodes representing user stories/flows and edges showing navigation paths (only when completed) architectureGraph: $ref: '#/components/schemas/SpecGraph' description: >- System architecture graph with C1/C2 level nodes and their relationships (only when completed) enrichedTechStack: type: array items: $ref: '#/components/schemas/SpecEnrichedTechStackItem' description: >- Enriched tech stack with detailed reasons, descriptions, and alternatives for each technology (only when completed) AsyncResponse: type: object required: - specId - status properties: specId: type: string description: Unique ID to poll for status (use with /api/spec-status/:specId) example: 507f1f77bcf86cd799439011 status: type: string enum: - pending description: Initial status Error: type: object required: - error - message properties: error: type: string description: Error type or code message: type: string description: Human-readable error message InsufficientCreditsError: type: object required: - error - message - generationsAvailable properties: error: type: string example: Insufficient credits message: type: string example: >- You have insufficient credits to generate a spec. Please purchase more credits or upgrade your plan. generationsAvailable: type: integer description: Number of credits currently available example: 0 CodingAgentSpecJson: type: object required: - executiveSummary - coreFunctionalities - techStack - milestones description: >- Simplified structured JSON for AI coding tools (excludes hours, personas, roles) properties: title: type: string description: Title of the specification executiveSummary: type: string description: Executive summary of the project coreFunctionalities: type: array items: $ref: '#/components/schemas/SpecCoreFunctionality' description: List of core functionalities techStack: type: array items: $ref: '#/components/schemas/SpecTechStackItem' description: Technology stack items techStackGrouped: type: object additionalProperties: type: array items: type: string description: Technology stack grouped by category milestones: type: array items: $ref: '#/components/schemas/CodingAgentMilestone' description: List of milestones HumanSpecJson: type: object required: - executiveSummary - coreFunctionalities - personas - techStack - milestones - totalHours - roles description: Full structured JSON with hours, personas, and roles for human review properties: title: type: string description: Title of the specification executiveSummary: type: string description: Executive summary of the project coreFunctionalities: type: array items: $ref: '#/components/schemas/SpecCoreFunctionality' description: List of core functionalities personas: type: array items: $ref: '#/components/schemas/SpecPersona' description: User personas techStack: type: array items: $ref: '#/components/schemas/SpecTechStackItem' description: Technology stack items techStackGrouped: type: object additionalProperties: type: array items: type: string description: Technology stack grouped by category milestones: type: array items: $ref: '#/components/schemas/HumanSpecMilestone' description: List of milestones with hours totalHours: type: number description: Total estimated hours for the project roles: type: array items: $ref: '#/components/schemas/SpecRole' description: Roles required for the project ZippedDocsUrl: type: object required: - platform - masterZipShortUrl properties: platform: type: string description: >- Hostname extracted from the documentation URL (e.g., 'stripe.com', 'docs.github.com') example: stripe.com masterZipShortUrl: type: string format: uri description: >- Short URL to download the zipped documentation archive for this platform masterMarkdownShortUrl: type: string format: uri description: Optional short URL to consolidated markdown file for this platform SpecGraph: type: object required: - nodes - edges properties: nodes: type: array items: $ref: '#/components/schemas/SpecGraphNode' description: Array of graph nodes edges: type: array items: $ref: '#/components/schemas/SpecGraphEdge' description: Array of graph edges SpecEnrichedTechStackItem: type: object required: - name - useFor - reason - description properties: name: type: string description: Name of the technology (e.g., React, PostgreSQL) useFor: type: string description: Category label (e.g., Frontend, Backend, Database) reason: type: string description: Why this technology was chosen for this specific project description: type: string description: Technical description of what the technology does link: type: string format: uri description: Official website or documentation URL helpfulLinks: type: array items: type: object properties: url: type: string format: uri description: URL to helpful resource description: type: string description: Description of the resource description: Array of helpful documentation and tutorial links alternatives: type: array items: type: object properties: name: type: string description: Name of the alternative technology link: type: string format: uri description: URL of the alternative technology description: type: string description: Description of the alternative description: Array of alternative technologies that could be used instead SpecCoreFunctionality: type: object required: - name - description properties: name: type: string description: Name of the core functionality description: type: string description: Description of the functionality priority: type: string enum: - High - Medium - Low description: Priority level of the functionality SpecTechStackItem: type: object required: - name - category properties: name: type: string description: Name of the technology category: type: string description: Category of the technology (e.g., Frontend, Backend, Database) CodingAgentMilestone: type: object required: - milestoneNumber - description - stories properties: milestoneNumber: type: integer description: Milestone number description: type: string description: Description of the milestone stories: type: array items: $ref: '#/components/schemas/CodingAgentStory' description: List of user stories in this milestone SpecPersona: type: object required: - title - description properties: title: type: string description: Title of the persona description: type: string description: Description of the persona primaryGoals: type: array items: type: string description: Primary goals of the persona painPoints: type: array items: type: string description: Pain points of the persona keyTasks: type: array items: type: string description: Key tasks of the persona HumanSpecMilestone: type: object required: - milestoneNumber - description - hours - stories properties: milestoneNumber: type: integer description: Milestone number description: type: string description: Description of the milestone hours: type: number description: Estimated hours for this milestone stories: type: array items: $ref: '#/components/schemas/HumanSpecStory' description: List of user stories in this milestone SpecRole: type: object required: - name - shortHand properties: name: type: string description: Full name of the role (e.g., Full Stack Developer) shortHand: type: string description: Short abbreviation for the role (e.g., FSD) SpecGraphNode: type: object required: - id - label properties: id: type: string description: Unique identifier for the node label: type: string description: Display label for the node type: type: string description: >- Node type category. For architectureGraph: "frontend", "api-services", "databases", or "external-services". For userFlowGraph: "flow", "role", etc. description: type: string description: Description of the node level: type: number description: >- Graph depth level (1, 2, 3...) for userFlowGraph nodes. Not present on architectureGraph nodes. hours: type: number description: Estimated hours for this node SpecGraphEdge: type: object required: - source - target properties: source: type: string description: Source node ID target: type: string description: Target node ID description: type: string description: Description of the relationship edgeType: type: string description: Type of edge relationship CodingAgentStory: type: object required: - title - subTasks properties: id: type: string description: Story identifier (e.g., US-001) title: type: string description: Title of the user story description: type: string description: Description of the user story acceptanceCriteria: type: array items: type: string description: List of acceptance criteria complexity: type: string description: Complexity estimate for the story subTasks: type: array items: $ref: '#/components/schemas/CodingAgentSubTask' description: List of subtasks for this story HumanSpecStory: type: object required: - title - hours - subTasks properties: id: type: string description: Story identifier (e.g., US-001) title: type: string description: Title of the user story description: type: string description: Description of the user story acceptanceCriteria: type: array items: type: string description: List of acceptance criteria hours: type: number description: Estimated hours for this story complexity: type: string description: Complexity estimate for the story subTasks: type: array items: $ref: '#/components/schemas/HumanSpecSubTask' description: List of subtasks for this story CodingAgentSubTask: type: object required: - description - complexity properties: id: type: string description: Subtask identifier description: type: string description: Description of the subtask complexity: type: string enum: - S - M - L - XL description: Complexity estimate HumanSpecSubTask: type: object required: - description - hours - complexity properties: id: type: string description: Subtask identifier description: type: string description: Description of the subtask hours: type: number description: Estimated hours for this subtask complexity: type: string description: Complexity estimate roles: type: array items: $ref: '#/components/schemas/SpecRole' description: Roles assigned to this subtask securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API key for authentication. Get your API key from https://pre.dev/projects/playground (Solo) or https://pre.dev/enterprise/dashboard?page=api (Enterprise). Use format: Bearer YOUR_API_KEY x-default: YOUR_API_KEY ````