Skip to main content
POST
/
fast-spec
curl --request POST \
--url https://api.pre.dev/fast-spec \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"input": "Build a SaaS project management tool with team collaboration, real-time updates, task tracking, and time logging",
"outputFormat": "url"
}'
{
  "endpoint": "fast_spec",
  "input": "<string>",
  "status": "completed",
  "success": true,
  "output": "<string>",
  "outputFormat": "url",
  "outputFileUrl": "<string>",
  "executionTime": 123,
  "predevUrl": "<string>",
  "lovableUrl": "<string>",
  "cursorUrl": "<string>",
  "v0Url": "<string>",
  "boltUrl": "<string>"
}

POST /fast-spec

Generate a quick, comprehensive project specification.

Overview

  • Cost: 10 credits
  • Use Cases: MVPs, prototypes, rapid iteration
  • Processing Time: ~30-40 seconds (sync) or instant return (async)
  • Output: Complete feature breakdown, architecture, milestones

Endpoint

POST https://api.pre.dev/fast-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:
ParameterTypeRequiredDescription
inputstringDescription of what you want to build
outputFormatstring"url" (default) - returns hosted URL, or "markdown" - returns raw markdown in response
currentContextstringCRITICAL: Existing project/codebase context. When provided, generates feature addition spec. When omitted, generates full new project spec with setup, deployment, docs, maintenance
docURLsstring[]Optional: Array of documentation URLs that Architect will reference when generating specifications. Useful for API documentation, design systems, or existing project docs
asyncbooleanfalse (default) - wait for completion, or true - return immediately with requestId for status polling
For file upload requests (multipart/form-data):
ParameterTypeRequiredDescription
fileFileOptional: File to be parsed as input (e.g., existing code, documentation, requirements). Can be used alone or combined with input text
inputstringOptional: Additional text description when using file upload. Can be empty string if using only file
outputFormatstring"url" (default) - returns hosted URL, or "markdown" - returns raw markdown in response
docURLsstring[]Optional: Array of documentation URLs that Architect will reference when generating specifications. Useful for API documentation, design systems, or existing project docs
asyncbooleanfalse (default) - wait for completion, or true - return immediately with requestId for status polling

Understanding currentContext

Omit currentContext (New Project):
{
  "input": "Build a task management SaaS"
}
Generates: Complete new project including:
  • Initial setup and scaffolding
  • Deployment configuration
  • Documentation structure
  • Support and maintenance guidelines
  • Infrastructure setup
  • CI/CD pipelines
  • Monitoring and logging
Provide currentContext (Feature Addition):
{
  "input": "Add real-time notifications and activity feed",
  "currentContext": "Existing Next.js task management app with Supabase, has auth, task CRUD, team features"
}
Generates: Incremental feature spec including:
  • New features only (respects existing architecture)
  • Integration points with current codebase
  • Migration considerations
  • No redundant setup/deployment (already exists)

Example: New Project

{
  "input": "Build a SaaS project management tool with team collaboration, real-time updates, task tracking, and time logging. Include user authentication and role-based permissions.",
  "outputFormat": "url"
}

Example: Feature Addition

{
  "input": "Add a calendar view and Gantt chart visualization to the existing project management tool",
  "currentContext": "We have a task management system with list and board views, user auth, and basic team features",
  "outputFormat": "url"
}

Example: Async Request

{
  "input": "Build a comprehensive e-commerce platform with inventory management",
  "outputFormat": "url",
  "async": true
}

Example: With Documentation URLs

{
  "input": "Build a customer support ticketing system with priority levels and file attachments",
  "outputFormat": "url",
  "docURLs": [
    "https://docs.pre.dev",
    "https://docs.stripe.com"
  ]
}

Example: With File Upload

// Prepare file upload
const formData = new FormData();
formData.append('file', fileInput.files[0]); // fileInput is your HTML file input
formData.append('input', '');
formData.append('outputFormat', 'url');
formData.append('docURLs', JSON.stringify(["https://docs.pre.dev"]));

const response = await fetch('http://localhost:3001/fast-spec', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

Example: File Upload with Additional Context

// Upload a requirements document and add context
const formData = new FormData();
formData.append('file', requirementsFile); // PDF or text file with requirements
formData.append('input', 'Please focus on the authentication and user management features from the uploaded requirements document');
formData.append('outputFormat', 'markdown');
formData.append('docURLs', JSON.stringify(["https://docs.pre.dev/auth"]));

Response

Success Response (Sync Mode)

{
  "endpoint": "fast_spec",
  "input": "Build a SaaS project management tool with team collaboration...",
  "status": "completed",
  "success": true,
  "output": "https://api.pre.dev/s/a6hFJRV6",
  "outputFormat": "url",
  "outputFileUrl": "https://api.pre.dev/s/a6hFJRV6",
  "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"
}
FieldTypeDescription
endpointstringEndpoint used: "fast_spec" or "deep_spec"
inputstringOriginal input text provided
statusstringCompletion status: "completed" when successful
successbooleanWhether the request succeeded
outputanyPrimary output - the hosted spec URL or markdown content
outputFormatstringFormat used: "url" or "markdown"
outputFileUrlstringURL where the spec file is hosted (downloadable markdown)
executionTimenumberProcessing time in milliseconds
predevUrlstringpre.dev project URL where you can view and edit the spec
lovableUrlstringDeep link to Lovable.dev with auto-submit prompt to implement the spec
cursorUrlstringDeep link to Cursor with prompt to download and implement the spec
v0UrlstringDeep link to Vercel v0 with prompt to implement the spec
boltUrlstringDeep link to Bolt.new with prompt to implement the spec
When outputFormat: "markdown":
{
  "endpoint": "fast_spec",
  "input": "Build a SaaS project management tool...",
  "status": "completed",
  "success": true,
  "output": "# Project Specification\n\n## Executive Summary...",
  "outputFormat": "markdown",
  "outputFileUrl": "https://api.pre.dev/s/a6hFJRV6",
  "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"
}

Success Response (Async Mode)

Immediate response when async: true:
{
  "specId": "507f1f77bcf86cd799439011",
  "status": "pending"
}
FieldTypeDescription
specIdstringUnique ID to poll for status (use with /api/spec-status/:specId)
statusstringInitial status: "pending"
Poll /api/spec-status/:specId to check progress.

Async Status Flow

  1. Pending → Initial queue state
  2. Processing → Actively generating spec
  3. Completed → Success, output available
  4. Failed → Error occurred
Typical processing times:
  • Fast Spec: 30-40 seconds
  • Deep Spec: 2-3 minutes
Poll every 10-15 seconds for best UX.

Output Structure: Milestones → Stories

Fast Spec follows a two-level hierarchy optimized for rapid development:
### - [ ] **Milestone 1**: 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

- [ ] **User Login** - (S): As a: registered user, I want to: log in securely, So that: I can access my account
  - **Acceptance Criteria:**
    - [ ] User can log in with correct credentials
    - [ ] Invalid credentials rejected with clear message
    - [ ] Session persists across browser tabs
    - [ ] Password reset option available

- [ ] **User Profile** - (M): As a: registered user, I want to: manage my profile, So that: I can update my information
  - **Acceptance Criteria:**
    - [ ] User can view and edit profile details
    - [ ] Shipping addresses can be saved
    - [ ] Password can be changed with re-authentication
    - [ ] Account can be deactivated
Key Characteristics:
  • ✅ High-level milestones group related features
  • ✅ User stories with acceptance criteria
  • ✅ Complexity estimates (XS, S, M, L, XL)
  • ❌ No granular implementation subtasks

Code Examples

cURL - Complete Flow

Synchronous Request:
curl -X POST https://api.pre.dev/fast-spec \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "input": "Build a real-time collaborative whiteboard with drawing tools, shapes, text, and team presence indicators",
    "outputFormat": "url"
  }'
Asynchronous Request with Polling:
# Step 1: Start async processing
RESPONSE=$(curl -X POST https://api.pre.dev/fast-spec \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "input": "Build a CRM with contact management, deal pipeline, and email integration",
    "async": true
  }')

SPEC_ID=$(echo $RESPONSE | jq -r '.specId')

# Step 2: Poll for status
while true; do
  STATUS=$(curl https://api.pre.dev/spec-status/$SPEC_ID \
    -H "Authorization: Bearer YOUR_API_KEY")

  STATE=$(echo $STATUS | jq -r '.status')

  if [ "$STATE" = "completed" ]; then
    echo "Spec ready!"
    echo $STATUS | jq -r '.output'
    break
  elif [ "$STATE" = "failed" ]; then
    echo "Processing failed"
    echo $STATUS | jq -r '.errorMessage'
    break
  fi

  echo "Status: $STATE - $(echo $STATUS | jq -r '.progress')"
  sleep 10
done

Python - Complete Implementation

import requests
import time
from typing import Dict, Any

class ArchitectAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.pre.dev"

    def generate_spec(
        self,
        input_text: str,
        current_context: str = None,
        output_format: str = "url",
        async_mode: bool = False
    ) -> Dict[str, Any]:
        """Generate a fast spec."""
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.api_key}"
        }

        payload = {
            "input": input_text,
            "outputFormat": output_format,
            "async": async_mode
        }

        if current_context:
            payload["currentContext"] = current_context

        response = requests.post(
            f"{self.base_url}/fast-spec",
            headers=headers,
            json=payload
        )

        response.raise_for_status()
        return response.json()

    def check_status(self, spec_id: str) -> Dict[str, Any]:
        """Check async processing status."""
        headers = {"Authorization": f"Bearer {self.api_key}"}

        response = requests.get(
            f"{self.base_url}/spec-status/{spec_id}",
            headers=headers
        )

        response.raise_for_status()
        return response.json()

    def wait_for_completion(self, spec_id: str, poll_interval: int = 10) -> Dict[str, Any]:
        """Wait for async processing to complete."""
        while True:
            status = self.check_status(spec_id)

            if status["status"] == "completed":
                return status
            elif status["status"] == "failed":
                raise Exception(f"Processing failed: {status.get('errorMessage')}")

            print(f"Status: {status['status']} - {status.get('progress', 'Processing...')}")
            time.sleep(poll_interval)

# Usage
api = ArchitectAPI(api_key="YOUR_API_KEY")

# Synchronous (wait for result)
result = api.generate_spec(
    input_text="Build a fitness tracking app with workout logging, progress charts, and social features",
    output_format="url"
)
print(f"Spec URL: {result['output']}")

# Asynchronous (poll for result)
response = api.generate_spec(
    input_text="Add AI meal planning and nutrition tracking to existing fitness app",
    current_context="Existing app has workout logging, user profiles, and basic social features built with React Native and Firebase",
    async_mode=True
)

result = api.wait_for_completion(response["specId"])
print(f"Spec ready: {result['output']}")

JavaScript/Node.js - Complete Implementation

const fetch = require('node-fetch');

class ArchitectAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.pre.dev';
  }

  async generateSpec({
    input,
    currentContext = null,
    outputFormat = 'url',
    async = false
  }) {
    const headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.apiKey}`
    };

    const payload = {
      input,
      outputFormat,
      async
    };

    if (currentContext) {
      payload.currentContext = currentContext;
    }

    const response = await fetch(`${this.baseUrl}/fast-spec`, {
      method: 'POST',
      headers,
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API request failed');
    }

    return response.json();
  }

  async checkStatus(specId) {
    const headers = { 'Authorization': `Bearer ${this.apiKey}` };

    const response = await fetch(
      `${this.baseUrl}/spec-status/${specId}`,
      { headers }
    );

    if (!response.ok) {
      throw new Error('Failed to check status');
    }

    return response.json();
  }

  async waitForCompletion(specId, pollInterval = 10000) {
    while (true) {
      const status = await this.checkStatus(specId);

      if (status.status === 'completed') {
        return status;
      } else if (status.status === 'failed') {
        throw new Error(`Processing failed: ${status.errorMessage}`);
      }

      console.log(`Status: ${status.status} - ${status.progress || 'Processing...'}`);
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
  }
}

// Usage Examples

// Synchronous
(async () => {
  const api = new ArchitectAPI('YOUR_API_KEY');

  try {
    const result = await api.generateSpec({
      input: 'Build an e-learning platform with video courses, quizzes, certificates, and student progress tracking'
    });

    console.log('Spec URL:', result.output);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

// With Documentation URLs
(async () => {
  const api = new ArchitectAPI('YOUR_API_KEY');

  try {
    const result = await api.generateSpec({
      input: 'Build a customer support ticketing system with priority levels and file attachments',
      docURLs: [
        'https://docs.pre.dev',
        'https://docs.stripe.com'
      ]
    });

    console.log('Spec URL:', result.output);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

// With File Upload
(async () => {
  const api = new ArchitectAPI('YOUR_API_KEY');

  try {
    // For file uploads, use multipart/form-data
    const formData = new FormData();
    formData.append('file', fileInput.files[0]);
    formData.append('input', 'Analyze the uploaded requirements document');
    formData.append('outputFormat', 'url');
    formData.append('docURLs', JSON.stringify(['https://docs.pre.dev']));

    const response = await fetch(`${api.baseUrl}/fast-spec`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${api.apiKey}`
        // Note: Don't set Content-Type for FormData - browser sets it automatically
      },
      body: formData
    });

    const result = await response.json();
    console.log('Spec URL:', result.output);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

// Asynchronous with polling
(async () => {
  const api = new ArchitectAPI('YOUR_API_KEY');

  try {
    // Start processing
    const response = await api.generateSpec({
      input: 'Add gamification with points, badges, and leaderboards',
      currentContext: 'Existing e-learning platform with courses and progress tracking',
      async: true
    });

    console.log('Spec ID:', response.specId);

    // Wait for completion
    const result = await api.waitForCompletion(response.specId);
    console.log('Spec ready:', result.output);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

TypeScript - Type-Safe Implementation

interface SpecRequest {
  input: string;
  currentContext?: string;
  outputFormat?: 'url' | 'markdown';
  docURLs?: string[];
  async?: boolean;
}

interface FileUploadRequest {
  file?: File;
  input?: string;
  outputFormat?: 'url' | 'markdown';
  docURLs?: string[];
  async?: boolean;
}

interface SpecResponse {
  output?: string;
  markdown?: string;
  outputFormat: 'url' | 'markdown';
  fileUrl: string;
}

interface AsyncResponse {
  specId: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
}

interface StatusResponse {
  _id?: string;
  created?: string;
  endpoint: 'fast_spec' | 'deep_spec';
  input: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  success: boolean;
  uploadedFileShortUrl?: string;
  uploadedFileName?: string;
  output?: any;
  outputFormat: 'markdown' | 'url';
  outputFileUrl?: string;
  executionTime?: number;
  predevUrl?: string;
  lovableUrl?: string;
  cursorUrl?: string;
  v0Url?: string;
  boltUrl?: string;
  errorMessage?: string;
  progress?: string;
}

class ArchitectAPI {
  private apiKey: string;
  private baseUrl: string = 'https://api.pre.dev';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async generateSpec(request: SpecRequest): Promise<SpecResponse | AsyncResponse> {
    const response = await fetch(`${this.baseUrl}/fast-spec`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify(request)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API request failed');
    }

    return response.json();
  }

  async checkStatus(specId: string): Promise<StatusResponse> {
    const response = await fetch(`${this.baseUrl}/spec-status/${specId}`, {
      headers: { 'Authorization': `Bearer ${this.apiKey}` }
    });

    if (!response.ok) {
      throw new Error('Failed to check status');
    }

    return response.json();
  }

  async waitForCompletion(specId: string, pollInterval: number = 10000): Promise<StatusResponse> {
    while (true) {
      const status = await this.checkStatus(specId);

      if (status.status === 'completed') {
        return status;
      } else if (status.status === 'failed') {
        throw new Error(`Processing failed: ${status.errorMessage}`);
      }

      console.log(`${status.status}: ${status.progress || 'Processing...'}`);
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
  }
}

What You Get

The generated specification includes:
  • Executive summary
  • Feature breakdown by category
  • Technical architecture recommendations
  • Implementation milestones with effort estimates
  • User stories and acceptance criteria
  • Task checklist with progress tracking
    • Task status legend: [ ][→][✓][⊘]
    • Update as your agent completes work
    • Keep both you and AI aligned on progress
  • Risk analysis and considerations
  • Markdown formatted for direct agent use

Using Task Tracking

As your agent implements features, actively manage progress:
  1. Mark tasks in progress: Change [ ] to [→] when starting
  2. Mark complete: Change [→] to [✓] when done
  3. Mark skipped: Change [ ] to [⊘] if skipping (with reason)
Pro Tip: Don’t let your agent skip tasks without questioning why. This keeps implementation comprehensive and on-track.

Best Practices

Writing Effective Input

  • Be specific about core features
  • Include business context and constraints
  • Mention technical preferences if any

Managing Your Agent

  • Actively interrupt to ensure tasks are checked off
  • Question every skipped task
  • Verify acceptance criteria before marking complete
  • Triple check that tests are written

Next: Deep Spec Endpoint

Generate ultra-detailed specifications for complex projects.

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

Body

input
string
required

Description of what you want to build or the feature you want to add

Example:

"Build a SaaS project management tool with team collaboration and real-time updates"

outputFormat
enum<string>
default:url

Output format: 'url' returns a hosted URL (default), 'markdown' returns raw markdown content

Available options:
url,
markdown
currentContext
string

CRITICAL: Existing project/codebase context. When provided, generates feature addition spec. When omitted, generates full new project spec with setup, deployment, docs, maintenance

Example:

"Existing Next.js app with Supabase, has auth, task CRUD, team features"

docURLs
string<uri>[]

Optional array of documentation URLs that Architect will reference when generating specifications

Example:
[
"https://docs.pre.dev",
"https://docs.stripe.com"
]
async
boolean
default:false

If true, returns immediately with requestId for status polling. If false (default), waits for completion

Response

Specification generated successfully

  • Option 1
  • Option 2
endpoint
enum<string>

Which endpoint was used

Available options:
fast_spec,
deep_spec
input
string

Original input text provided

status
enum<string>

Completion status

Available options:
completed
success
boolean

Whether the request succeeded

output

Primary output - the hosted spec URL or markdown content

outputFormat
enum<string>

Format used

Available options:
url,
markdown
outputFileUrl
string<uri>

URL where the spec file is hosted (downloadable markdown)

executionTime
integer

Processing time in milliseconds

predevUrl
string<uri>

pre.dev project URL where you can view and edit the spec

lovableUrl
string<uri>

Deep link to Lovable.dev with auto-submit prompt to implement the spec

cursorUrl
string

Deep link to Cursor with prompt to download and implement the spec

v0Url
string<uri>

Deep link to Vercel v0 with prompt to implement the spec

boltUrl
string<uri>

Deep link to Bolt.new with prompt to implement the spec

I