> ## 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. # Get Spec > Monitor the progress of asynchronous specification processing requests. # GET /api/spec-status/:specId Check the status of an asynchronous specification processing request. ## Overview When you make an async request (`"async": true`), use this endpoint to poll for completion status. ## Endpoint ``` GET https://api.pre.dev/spec-status/:specId ``` ## Parameters | Parameter | Location | Required | Description | | --------- | -------- | -------- | ------------------------------------------- | | `specId` | Path | ✅ | Spec ID returned from async spec processing | ## Example Request ```bash theme={null} curl https://api.pre.dev/spec-status/507f1f77bcf86cd799439011 \ -H "Authorization: Bearer YOUR_API_KEY" ``` The `specId` in the URL is the value returned as `specId` from the async spec generation request. ## Response ### Pending ```json theme={null} { "_id": "507f1f77bcf86cd799439011", "created": "2025-10-03T10:00:00Z", "endpoint": "fast_spec", "input": "Build a SaaS project management tool...", "status": "pending", "success": false, "progress": 0, "progressMessage": "Initializing..." } ``` ### Processing ```json theme={null} { "_id": "507f1f77bcf86cd799439011", "created": "2025-10-03T10:00:00Z", "endpoint": "fast_spec", "input": "Build a SaaS project management tool...", "status": "processing", "success": false, "progress": 45, "progressMessage": "Generating User Stories...", "creditsUsed": 3 } ``` ### Completed ```json theme={null} { "_id": "507f1f77bcf86cd799439011", "created": "2025-10-03T10:00:00Z", "endpoint": "fast_spec", "input": "Build a SaaS project management tool...", "status": "completed", "success": true, "humanSpecUrl": "https://api.pre.dev/s/a6hFJRV6", "totalHumanHours": 120, "architectureInfographicUrl": "https://res.cloudinary.com/dfvg7gm6w/image/upload/v1765403270/infographics/arch_infographic_cfac141b_1765403269989_0.jpg", "codingAgentSpecUrl": "https://api.pre.dev/s/a6hFJRV7", "codingAgentSpecJson": { "title": "Task Management App", "executiveSummary": "A modern task management application...", "coreFunctionalities": [{ "name": "Task CRUD", "description": "Create, read, update, delete tasks", "priority": "High" }], "techStack": [{ "name": "React", "category": "Frontend" }], "techStackGrouped": { "Frontend": ["React", "TailwindCSS"] }, "milestones": [{ "milestoneNumber": 1, "description": "Core Task Management", "stories": [] }] }, "codingAgentSpecMarkdown": "# Task Management App\n\n## Executive Summary\n...", "humanSpecJson": { "title": "Task Management App", "executiveSummary": "A modern task management application...", "coreFunctionalities": [{ "name": "Task CRUD", "description": "Create, read, update, delete tasks", "priority": "High" }], "personas": [{ "title": "Project Manager", "description": "Manages team tasks" }], "techStack": [{ "name": "React", "category": "Frontend" }], "techStackGrouped": { "Frontend": ["React", "TailwindCSS"] }, "milestones": [{ "milestoneNumber": 1, "description": "Core Task Management", "hours": 40, "stories": [] }], "totalHours": 120, "roles": [{ "name": "Full Stack Developer", "shortHand": "FSD" }] }, "humanSpecMarkdown": "# Task Management App\n\n## Executive Summary\n...", "executionTime": 38500, "predevUrl": "https://pre.dev/projects/abc123", "creditsUsed": 7, "progress": 100, "progressMessage": "Completed successfully", "userFlowGraph": { "nodes": [ { "id": "authentication", "label": "Authentication", "type": "flow", "level": 1 }, { "id": "dashboard", "label": "Dashboard", "type": "flow", "level": 2 }, { "id": "task_management", "label": "Task Management", "type": "flow", "level": 3 } ], "edges": [ { "source": "authentication", "target": "dashboard" }, { "source": "dashboard", "target": "task_management" } ] }, "architectureGraph": { "nodes": [ { "id": "web_main_app", "label": "React Web Application", "type": "frontend" }, { "id": "api_main_service", "label": "Node.js API Service", "type": "api-services" }, { "id": "db_primary", "label": "PostgreSQL Database", "type": "databases" } ], "edges": [ { "source": "web_main_app", "target": "api_main_service", "edgeType": "uses" }, { "source": "api_main_service", "target": "db_primary", "edgeType": "reads_writes" } ] }, "enrichedTechStack": [ { "name": "React", "useFor": "Frontend", "reason": "Component-based architecture ideal for building interactive task management UIs with real-time updates", "description": "A JavaScript library for building user interfaces with a virtual DOM for efficient rendering", "link": "https://react.dev", "alternatives": [{ "name": "Vue.js", "link": "https://vuejs.org", "description": "Progressive JavaScript framework" }] } ] } ``` ### Failed ```json theme={null} { "_id": "507f1f77bcf86cd799439011", "created": "2025-10-03T10:00:00Z", "endpoint": "fast_spec", "input": "Build a SaaS project management tool...", "status": "failed", "success": false, "errorMessage": "Invalid input format", "executionTime": 5000, "progress": 0, "progressMessage": "Failed to generate specification" } ``` ## Response Fields | Field | Type | Description | | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `_id` | string | MongoDB ObjectId of the spec request | | `created` | string | ISO timestamp when the request was created | | `endpoint` | string | Which endpoint was used: `"fast_spec"` or `"deep_spec"` | | `input` | string | Original input text provided | | `status` | string | Current status: `"pending"`, `"processing"`, `"completed"`, or `"failed"` | | `success` | boolean | Whether the request succeeded | | `uploadedFileShortUrl` | string | Short URL for uploaded file (if file was uploaded) | | `uploadedFileName` | string | Name of uploaded file (if file was uploaded) | | `humanSpecUrl` | string | URL where the human-readable spec is hosted - downloadable markdown (only when completed) | | `totalHumanHours` | number | Estimated total hours for a human to implement the spec (only when completed) | | `architectureInfographicUrl` | string | URL to a visual architecture infographic/diagram for the specification (only when completed) | | `codingAgentSpecUrl` | string | URL where the coding agent spec format is hosted - downloadable markdown (only when completed) | | `codingAgentSpecJson` | object | Structured JSON spec optimized for AI coding assistants (only when completed) | | `codingAgentSpecMarkdown` | string | Markdown spec optimized for AI coding assistants (only when completed) | | `humanSpecJson` | object | Full structured JSON spec with hours, personas, and roles (only when completed) | | `humanSpecMarkdown` | string | Full markdown spec with all details for human review (only when completed) | | `executionTime` | number | Processing time in milliseconds (only when completed or failed) | | `predevUrl` | string | pre.dev project URL where you can view and edit the spec (only when completed) | | `errorMessage` | string | Error description (only when failed) | | `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 | | `progress` | number | Overall progress percentage (0-100) | | `progressMessage` | string | Detailed progress message (e.g., "Generating User Stories...") | | `userFlowGraph` | object | User flow graph with `nodes` (id, label, type, description, level) and `edges` (source, target, edgeType). Nodes include a numeric `level` (1, 2, 3...) indicating graph depth for layered rendering (only when completed) | | `architectureGraph` | object | System architecture graph with `nodes` (id, label, type, description) and `edges` (source, target, edgeType). Node `type` is one of: `"frontend"`, `"api-services"`, `"databases"`, `"external-services"` (only when completed) | | `enrichedTechStack` | array | Enriched tech stack items with `name`, `useFor`, `reason`, `description`, `link`, `helpfulLinks`, and `alternatives` for each technology (only when completed) | ## Polling Best Practices ### Polling Interval * **Recommended:** Poll every 10-15 seconds * **Minimum:** Don't poll more frequently than every 5 seconds * **Maximum:** No need to poll more than every 30 seconds ### Example Polling Script ```bash theme={null} #!/bin/bash SPEC_ID="507f1f77bcf86cd799439011" API_KEY="YOUR_API_KEY" while true; do RESPONSE=$(curl -s https://api.pre.dev/spec-status/$SPEC_ID \ -H "Authorization: Bearer $API_KEY") STATUS=$(echo $RESPONSE | jq -r '.status') case $STATUS in "completed") echo "✅ Spec processing completed!" echo $RESPONSE | jq -r '.codingAgentSpecUrl' break ;; "failed") echo "❌ Spec processing failed:" echo $RESPONSE | jq -r '.errorMessage' break ;; "pending"|"processing") echo "$(date): $STATUS - $(echo $RESPONSE | jq -r '.progress')% - $(echo $RESPONSE | jq -r '.progressMessage')" sleep 10 ;; *) echo "Unknown status: $STATUS" break ;; esac done ``` ### Python Polling Example ```python theme={null} import requests import time from typing import Dict, Any def poll_spec_status(api_key: str, spec_id: str, poll_interval: int = 10) -> Dict[str, Any]: """Poll for spec processing completion.""" while True: response = requests.get( f'https://api.pre.dev/spec-status/{spec_id}', headers={'Authorization': f'Bearer {api_key}'} ) response.raise_for_status() data = response.json() status = data['status'] if status == 'completed': print("✅ Spec processing completed!") return data elif status == 'failed': print(f"❌ Spec processing failed: {data.get('errorMessage')}") raise Exception(f"Processing failed: {data.get('errorMessage')}") else: print(f"⏳ {status}: {data.get('progress', 0)}% - {data.get('progressMessage', 'Processing...')}") time.sleep(poll_interval) # Usage result = poll_spec_status("YOUR_API_KEY", "507f1f77bcf86cd799439011") print(f"Spec URL: {result['codingAgentSpecUrl']}") ``` ### JavaScript Polling Example ```javascript theme={null} async function pollSpecStatus(apiKey, specId, pollInterval = 10000) { while (true) { const response = await fetch( `https://api.pre.dev/spec-status/${specId}`, { headers: { 'Authorization': `Bearer ${apiKey}` } } ); if (!response.ok) { throw new Error('Failed to check status'); } const data = await response.json(); const status = data.status; if (status === 'completed') { console.log('✅ Spec processing completed!'); return data; } else if (status === 'failed') { console.error(`❌ Spec processing failed: ${data.errorMessage}`); throw new Error(`Processing failed: ${data.errorMessage}`); } else { console.log(`⏳ ${status}: ${data.progress || 0}% - ${data.progressMessage || 'Processing...'}`); await new Promise(resolve => setTimeout(resolve, pollInterval)); } } } // Usage try { const result = await pollSpecStatus('YOUR_API_KEY', '507f1f77bcf86cd799439011'); console.log(`Spec URL: ${result.codingAgentSpecUrl}`); } catch (error) { console.error('Error:', error.message); } ``` ## Expected Processing Times | Spec Type | Typical Time | Maximum Expected | | --------- | ------------- | ---------------- | | Fast Spec | 30-40 seconds | 2 minutes | | Deep Spec | 2-3 minutes | 5 minutes | **Note:** Times can vary based on input complexity and system load. ## Error Handling ### Common Issues **Spec ID Not Found:** ```json theme={null} { "error": "Request not found", "message": "No request found with ID: 507f1f77bcf86cd799439011" } ``` *Cause:* Invalid spec ID or request expired **Unauthorized:** ```json theme={null} { "error": "Unauthorized", "message": "Invalid API key" } ``` *Cause:* Invalid or missing API key ## Best Practices ### User Experience * Show a loading indicator while polling * Display progress messages to users * Set a reasonable timeout (e.g., 30 minutes) * Provide a way to cancel or retry ### Rate Limiting * Respect the polling interval recommendations * Implement exponential backoff for retries * Handle rate limit responses gracefully ### Monitoring * Log polling attempts for debugging * Track completion times for performance monitoring * Alert on unusual failure rates View all available API endpoints. ## OpenAPI ````yaml GET /spec-status/{specId} 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: /spec-status/{specId}: get: tags: - Status summary: Get Spec Status description: >- Check the status of an asynchronous specification processing request. Use this endpoint to poll for completion when you make an async request (async: true). operationId: getSpecStatus parameters: - name: specId in: path required: true description: The unique ID returned from an async spec generation request schema: type: string example: 507f1f77bcf86cd799439011 responses: '200': description: Status retrieved successfully content: application/json: schema: $ref: '#/components/schemas/StatusResponse' '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 '404': description: Not Found - Spec ID not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Request not found message: 'No request found with ID: 507f1f77bcf86cd799439011' security: - apiKeyAuth: [] components: schemas: StatusResponse: type: object properties: _id: type: string description: MongoDB ObjectId of the spec request created: type: string format: date-time description: ISO timestamp when the request was created 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: - pending - processing - completed - failed description: Current status success: type: boolean description: Whether the request succeeded uploadedFileShortUrl: type: string description: Short URL for uploaded file (if file was uploaded) uploadedFileName: type: string description: Name of uploaded file (if file was uploaded) humanSpecUrl: type: string format: uri description: URL where the human-readable spec is hosted (only when completed) totalHumanHours: type: number description: >- Estimated total hours for a human to implement the spec (only when completed) architectureInfographicUrl: type: string format: uri description: >- URL to a visual architecture infographic/diagram for the specification (only when completed) codingAgentSpecUrl: type: string format: uri description: >- URL where the coding agent spec format is hosted (only when completed) codingAgentSpecJson: $ref: '#/components/schemas/CodingAgentSpecJson' description: >- Structured JSON spec optimized for AI coding assistants (only when completed) codingAgentSpecMarkdown: type: string description: >- Markdown spec optimized for AI coding assistants (only when completed) humanSpecJson: $ref: '#/components/schemas/HumanSpecJson' description: >- Full structured JSON spec with hours, personas, and roles (only when completed) humanSpecMarkdown: type: string description: >- Full markdown spec with all details for human review (only when completed) executionTime: type: integer description: Processing time in milliseconds (only when completed or failed) predevUrl: type: string format: uri description: pre.dev project URL (only when completed) zippedDocsUrls: type: array description: >- Array of scraped documentation archives (only when completed). Empty array if no docURLs provided or scraping fails items: $ref: '#/components/schemas/ZippedDocsUrl' errorMessage: type: string description: Error description (only when failed) progress: type: string description: Human-readable progress description 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) Error: type: object required: - error - message properties: error: type: string description: Error type or code message: type: string description: Human-readable error message 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 ````