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": "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": "Generating specification..."
}

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,
  "codingAgentSpecUrl": "https://api.pre.dev/s/a6hFJRV7",
  "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",
  "progress": "Completed successfully"
}

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": "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)
`codingAgentSpecUrl`	string	URL where the coding agent spec format is hosted - downloadable markdown (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)
`progress`	string	Human-readable progress description

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')"
      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', '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 || '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)

codingAgentSpecUrl

string<uri>

URL where the coding agent spec format is hosted (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

zippedDocsUrls.platform

string

required

Hostname extracted from the documentation URL (e.g., 'stripe.com', 'docs.github.com')

Example:

"stripe.com"

zippedDocsUrls.masterZipShortUrl

string<uri>

required

Short URL to download the zipped documentation archive for this platform

zippedDocsUrls.masterMarkdownShortUrl

string<uri>

Optional short URL to consolidated markdown file for this platform

errorMessage

string

Error description (only when failed)

progress

string

Human-readable progress description

Using the API

Spec Generation

Spec Management

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

Using the API

Spec Generation

Spec Management

​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