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

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

{
  "_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

{
  "_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

{
  "_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",
  "lovableUrl": "https://lovable.dev/?autosubmit=true#prompt=First%20download%20https%3A%2F%2Fapi.pre.dev%2Fs%2Fa6hFJRV6%2C%20then%20save%20it%20to%20a%20file%20called%20%22spec.md%22%20and%20then%20parse%20it%20and%20implement%20it%20step%20by%20step",
  "cursorUrl": "cursor://anysphere.cursor-deeplink/prompt?text=First+download+https%3A%2F%2Fapi.pre.dev%2Fs%2Fa6hFJRV6%2C+then+save+it+to+a+file+called+%22spec.md%22+and+then+parse+it+and+implement+it+step+by+step",
  "v0Url": "https://v0.dev/chat?q=First%20download%20https%3A%2F%2Fapi.pre.dev%2Fs%2Fa6hFJRV6%2C%20then%20save%20it%20to%20a%20file%20called%20%22spec.md%22%20and%20then%20parse%20it%20and%20implement%20it%20step%20by%20step",
  "boltUrl": "https://bolt.new?prompt=First%20download%20https%3A%2F%2Fapi.pre.dev%2Fs%2Fa6hFJRV6%2C%20then%20save%20it%20to%20a%20file%20called%20%22spec.md%22%20and%20then%20parse%20it%20and%20implement%20it%20step%20by%20step",
  "creditsUsed": 7,
  "progress": 100,
  "progressMessage": "Completed successfully",
  "userFlowGraph": {
    "nodes": [
      { "id": "authentication", "label": "Authentication", "type": "flow" },
      { "id": "dashboard", "label": "Dashboard", "type": "flow" },
      { "id": "task_management", "label": "Task Management", "type": "flow" }
    ],
    "edges": [
      { "source": "authentication", "target": "dashboard" },
      { "source": "dashboard", "target": "task_management" }
    ]
  },
  "architectureGraph": {
    "nodes": [
      { "id": "system_web_app", "label": "Web Application", "type": "system", "level": "C1" },
      { "id": "system_api", "label": "API Server", "type": "system", "level": "C2" },
      { "id": "system_database", "label": "Database", "type": "system", "level": "C2" }
    ],
    "edges": [
      { "source": "system_web_app", "target": "system_api", "edgeType": "uses" },
      { "source": "system_api", "target": "system_database", "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

{
  "_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)
`lovableUrl`	string	Deep link to Lovable.dev with auto-submit prompt to implement the spec (only when completed)
`cursorUrl`	string	Deep link to Cursor with prompt to download and implement the spec (only when completed)
`v0Url`	string	Deep link to Vercel v0 with prompt to implement the spec (only when completed)
`boltUrl`	string	Deep link to Bolt.new with prompt to implement 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) and `edges` (source, target, edgeType). Represents user stories and navigation flows (only when completed)
`architectureGraph`	object	System architecture graph with `nodes` (id, label, type, level, description) and `edges` (source, target, edgeType). Shows C1/C2 level system components (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

#!/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

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

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:

{
  "error": "Request not found",
  "message": "No request found with ID: 507f1f77bcf86cd799439011"
}

Cause: Invalid spec ID or request expired Unauthorized:

{
  "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

Back to API Reference

View all available API endpoints.

Authorizations

Authorization

string

header

default:YOUR_API_KEY

required

API key for authentication. Get your API key from https://pre.dev/projects/playground (Solo) or https://pre.dev/enterprise/dashboard?page=api (Enterprise). Use format: Bearer YOUR_API_KEY

Path Parameters

specId

string

required

The unique ID returned from an async spec generation request

Example:

"507f1f77bcf86cd799439011"

Response

Status retrieved successfully

_id

string

MongoDB ObjectId of the spec request

created

string<date-time>

ISO timestamp when the request was created

endpoint

enum<string>

Which endpoint was used

Available options:

fast_spec,

deep_spec

input

string

Original input text provided

status

enum<string>

Current status

Available options:

pending,

processing,

completed,

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<uri>

URL where the human-readable spec is hosted (only when completed)

totalHumanHours

number

Estimated total hours for a human to implement the spec (only when completed)

architectureInfographicUrl

string<uri>

URL to a visual architecture infographic/diagram for the specification (only when completed)

codingAgentSpecUrl

string<uri>

URL where the coding agent spec format is hosted (only when completed)

codingAgentSpecJson

object

Structured JSON spec optimized for AI coding assistants (only when completed)

Show child attributes

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)

Show child attributes

humanSpecMarkdown

string

Full markdown spec with all details for human review (only when completed)

executionTime

integer

Processing time in milliseconds (only when completed or failed)

predevUrl

string<uri>

pre.dev project URL (only when completed)

lovableUrl

string<uri>

Deep link to Lovable.dev (only when completed)

cursorUrl

string

Deep link to Cursor (only when completed)

v0Url

string<uri>

Deep link to Vercel v0 (only when completed)

boltUrl

string<uri>

Deep link to Bolt.new (only when completed)

zippedDocsUrls

object[]

Array of scraped documentation archives (only when completed). Empty array if no docURLs provided or scraping fails

Show child attributes

errorMessage

string

Error description (only when failed)

progress

string

Human-readable progress description

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

Overview

API Reference

SDKs

Get Spec

GET /api/spec-status/:specId

Overview

Endpoint

Parameters

Example Request

Response

Pending

Processing

Completed

Failed

Response Fields

Polling Best Practices

Polling Interval

Example Polling Script

Python Polling Example

JavaScript Polling Example

Expected Processing Times

Error Handling

Common Issues

Best Practices

User Experience

Rate Limiting

Monitoring

Back to API Reference

Authorizations

Path Parameters

Response

Overview

API Reference

SDKs

​GET /api/spec-status/:specId

​Overview

​Endpoint

​Parameters

​Example Request

​Response

​Pending

​Processing

​Completed

​Failed

​Response Fields

​Polling Best Practices

​Polling Interval

​Example Polling Script

​Python Polling Example

​JavaScript Polling Example

​Expected Processing Times

​Error Handling

​Common Issues

​Best Practices

​User Experience

​Rate Limiting

​Monitoring

Back to API Reference

Authorizations

Path Parameters

Response

GET /api/spec-status/:specId

Overview

Endpoint

Parameters

Example Request

Response

Pending

Processing

Completed

Failed

Response Fields

Polling Best Practices

Polling Interval

Example Polling Script

Python Polling Example

JavaScript Polling Example

Expected Processing Times

Error Handling

Common Issues

Best Practices

User Experience

Rate Limiting

Monitoring